@abraca/mcp 1.6.0 → 1.8.1

package/dist/abracadabra-mcp.esm.js

@@ -3757,7 +3757,7 @@ const propertyKeyTypes = new Set([
 	"number",
 	"symbol"
 ]);
-function escapeRegex(str) {
+function escapeRegex$1(str) {
 	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function clone(inst, def, params) {
@@ -4468,7 +4468,7 @@ const $ZodCheckUpperCase = /* @__PURE__ */ $constructor("$ZodCheckUpperCase", (i
 });
 const $ZodCheckIncludes = /* @__PURE__ */ $constructor("$ZodCheckIncludes", (inst, def) => {
 	$ZodCheck.init(inst, def);
-	const escapedRegex = escapeRegex(def.includes);
+	const escapedRegex = escapeRegex$1(def.includes);
 	const pattern = new RegExp(typeof def.position === "number" ? `^.{${def.position}}${escapedRegex}` : escapedRegex);
 	def.pattern = pattern;
 	inst._zod.onattach.push((inst) => {
@@ -4491,7 +4491,7 @@ const $ZodCheckIncludes = /* @__PURE__ */ $constructor("$ZodCheckIncludes", (ins
 });
 const $ZodCheckStartsWith = /* @__PURE__ */ $constructor("$ZodCheckStartsWith", (inst, def) => {
 	$ZodCheck.init(inst, def);
-	const pattern = new RegExp(`^${escapeRegex(def.prefix)}.*`);
+	const pattern = new RegExp(`^${escapeRegex$1(def.prefix)}.*`);
 	def.pattern ?? (def.pattern = pattern);
 	inst._zod.onattach.push((inst) => {
 		const bag = inst._zod.bag;
@@ -4513,7 +4513,7 @@ const $ZodCheckStartsWith = /* @__PURE__ */ $constructor("$ZodCheckStartsWith",
 });
 const $ZodCheckEndsWith = /* @__PURE__ */ $constructor("$ZodCheckEndsWith", (inst, def) => {
 	$ZodCheck.init(inst, def);
-	const pattern = new RegExp(`.*${escapeRegex(def.suffix)}$`);
+	const pattern = new RegExp(`.*${escapeRegex$1(def.suffix)}$`);
 	def.pattern ?? (def.pattern = pattern);
 	inst._zod.onattach.push((inst) => {
 		const bag = inst._zod.bag;
@@ -5545,7 +5545,7 @@ const $ZodEnum = /* @__PURE__ */ $constructor("$ZodEnum", (inst, def) => {
 	const values = getEnumValues(def.entries);
 	const valuesSet = new Set(values);
 	inst._zod.values = valuesSet;
-	inst._zod.pattern = new RegExp(`^(${values.filter((k) => propertyKeyTypes.has(typeof k)).map((o) => typeof o === "string" ? escapeRegex(o) : o.toString()).join("|")})$`);
+	inst._zod.pattern = new RegExp(`^(${values.filter((k) => propertyKeyTypes.has(typeof k)).map((o) => typeof o === "string" ? escapeRegex$1(o) : o.toString()).join("|")})$`);
 	inst._zod.parse = (payload, _ctx) => {
 		const input = payload.value;
 		if (valuesSet.has(input)) return payload;
@@ -5563,7 +5563,7 @@ const $ZodLiteral = /* @__PURE__ */ $constructor("$ZodLiteral", (inst, def) => {
 	if (def.values.length === 0) throw new Error("Cannot create literal schema with no valid values");
 	const values = new Set(def.values);
 	inst._zod.values = values;
-	inst._zod.pattern = new RegExp(`^(${def.values.map((o) => typeof o === "string" ? escapeRegex(o) : o ? escapeRegex(o.toString()) : String(o)).join("|")})$`);
+	inst._zod.pattern = new RegExp(`^(${def.values.map((o) => typeof o === "string" ? escapeRegex$1(o) : o ? escapeRegex$1(o.toString()) : String(o)).join("|")})$`);
 	inst._zod.parse = (payload, _ctx) => {
 		const input = payload.value;
 		if (values.has(input)) return payload;
@@ -19965,6 +19965,47 @@ function signChallenge(challengeB64, privateKey) {
 	return toBase64url(sign(challenge, privateKey));
 }
 
+//#endregion
+//#region packages/mcp/src/mentions.ts
+/**
+* Mention parsing for chat messages.
+*
+* Recognizes `@alias` tokens (case-insensitive, word-boundary) so the agent
+* can decide whether a group-chat message is directed at it.
+*/
+/** Escape regex metacharacters in an alias string. */
+function escapeRegex(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Build a regex that matches `@<alias>` for any of the given aliases.
+* Requires a non-word char (or start) before `@` and a word boundary after the alias
+* so `@Claude` matches but `email@claudesomething` does not.
+*/
+function buildMentionRegex(aliases) {
+	const cleaned = aliases.map((a) => a.trim()).filter((a) => a.length > 0);
+	if (cleaned.length === 0) return null;
+	const alt = cleaned.map(escapeRegex).join("|");
+	return new RegExp(`(?:^|[^\\w@])@(?:${alt})\\b`, "i");
+}
+/** Returns true if `text` contains `@alias` for any alias (case-insensitive). */
+function containsMention(text, aliases) {
+	const re = buildMentionRegex(aliases);
+	if (!re) return false;
+	return re.test(text);
+}
+/**
+* Remove `@alias` tokens from the text. Leaves surrounding whitespace tidy so
+* the cleaned prompt reads naturally (e.g. `"@Claude help"` → `"help"`).
+*/
+function stripMention(text, aliases) {
+	const cleaned = aliases.map((a) => a.trim()).filter((a) => a.length > 0);
+	if (cleaned.length === 0) return text;
+	const alt = cleaned.map(escapeRegex).join("|");
+	const re = new RegExp(`(^|\\s)@(?:${alt})\\b[,:]?\\s*`, "gi");
+	return text.replace(re, (_m, lead) => lead ? " " : "").replace(/\s{2,}/g, " ").trim();
+}
+
 //#endregion
 //#region packages/mcp/src/server.ts
 /**
@@ -19975,7 +20016,10 @@ function signChallenge(challengeB64, privateKey) {
 * Use switchSpace(docId) to change the active space.
 */
 const IDLE_TIMEOUT_MS = 300 * 1e3;
-var AbracadabraMCPServer = class {
+var AbracadabraMCPServer = class AbracadabraMCPServer {
+	static {
+		this.TOOL_HISTORY_MAX = 20;
+	}
 	constructor(config) {
 		this._serverInfo = null;
 		this._rootDocId = null;
@@ -19992,6 +20036,7 @@ var AbracadabraMCPServer = class {
 		this._typingInterval = null;
 		this._lastChatChannel = null;
 		this._signFn = null;
+		this._toolHistory = [];
 		this.config = config;
 		this.client = new AbracadabraClient({
 			url: config.url,
@@ -20004,6 +20049,14 @@ var AbracadabraMCPServer = class {
 	get agentColor() {
 		return this.config.agentColor || "hsl(270, 80%, 60%)";
 	}
+	get triggerMode() {
+		return this.config.triggerMode ?? "mention+task";
+	}
+	get mentionAliases() {
+		const explicit = this.config.mentionAliases?.filter((a) => a.trim().length > 0);
+		if (explicit && explicit.length > 0) return explicit;
+		return [this.agentName];
+	}
 	get serverInfo() {
 		return this._serverInfo;
 	}
@@ -20044,7 +20097,7 @@ var AbracadabraMCPServer = class {
 				await this.client.loginWithKey(keypair.publicKeyB64, signFn);
 			} else throw err;
 		}
-		console.error(`[abracadabra-mcp] Authenticated as ${this.agentName} (${keypair.publicKeyB64.slice(0, 12)}...)`);
+		console.error(`[abracadabra-mcp] Authenticated as ${this.agentName} (pubkey=${keypair.publicKeyB64})`);
 		this._serverInfo = await this.client.serverInfo();
 		let initialDocId = this._serverInfo.index_doc_id ?? null;
 		try {
@@ -20111,6 +20164,8 @@ var AbracadabraMCPServer = class {
 		provider.awareness.setLocalStateField("status", null);
 		provider.awareness.setLocalStateField("activeToolCall", null);
 		provider.awareness.setLocalStateField("statusContext", null);
+		provider.awareness.setLocalStateField("turnId", null);
+		provider.awareness.setLocalStateField("toolHistory", []);
 		const conn = {
 			doc,
 			provider,
@@ -20145,6 +20200,17 @@ var AbracadabraMCPServer = class {
 	getTrashMap() {
 		return this._activeConnection?.doc.getMap("doc-trash") ?? null;
 	}
+	/** Get plugin names enabled in the active space via space-plugins Y.Map. */
+	getEnabledPluginNames() {
+		const doc = this._activeConnection?.doc;
+		if (!doc) return [];
+		const pluginsMap = doc.getMap("space-plugins");
+		const names = [];
+		pluginsMap.forEach((value, key) => {
+			if ((value?.toJSON ? value.toJSON() : value)?.enabled) names.push(key);
+		});
+		return names;
+	}
 	/**
 	* Get or create a child provider for a given document ID.
 	* Caches providers and waits for sync before returning.
@@ -20223,6 +20289,7 @@ var AbracadabraMCPServer = class {
 	_observeRootAwareness(provider) {
 		const selfId = provider.awareness.clientID;
 		provider.awareness.on("change", () => {
+			if (this.triggerMode === "mention") return;
 			const states = provider.awareness.getStates();
 			for (const [clientId, state] of states) {
 				if (clientId === selfId) continue;
@@ -20235,6 +20302,7 @@ var AbracadabraMCPServer = class {
 				const user = state["user"];
 				const senderName = user && typeof user === "object" && typeof user.name === "string" ? user.name : "Unknown";
 				console.error(`[abracadabra-mcp] Handling ai:task id=${id} from ${senderName}: ${text.slice(0, 80)}`);
+				this._beginTurn();
 				this.setAutoStatus("thinking");
 				this._dispatchAiTask({
 					id,
@@ -20297,9 +20365,28 @@ var AbracadabraMCPServer = class {
 			if (data.sender_id && data.sender_id === this._userId) return;
 			const channel = data.channel;
 			const docId = channel?.startsWith("group:") ? channel.slice(6) : "";
-			if (channel?.startsWith("dm:")) {
+			const isDM = channel?.startsWith("dm:") ?? false;
+			const isGroup = channel?.startsWith("group:") ?? false;
+			if (isDM) {
 				const parts = channel.split(":");
-				if (parts.length === 3 && parts[1] !== this._userId && parts[2] !== this._userId) return;
+				if (parts.length === 3 && parts[1] !== this._userId && parts[2] !== this._userId) {
+					console.error(`[abracadabra-mcp] Dropping DM: agent _userId=${this._userId} not in channel parts=[${parts[1]}, ${parts[2]}] — channel='${channel}'. The dashboard's awareness likely points at a stale Claude identity.`);
+					return;
+				}
+			}
+			const mode = this.triggerMode;
+			const content = typeof data.content === "string" ? data.content : "";
+			let dispatchContent = content;
+			if (isGroup) {
+				if (mode === "task") return;
+				if (mode === "mention" || mode === "mention+task") {
+					const aliases = this.mentionAliases;
+					if (!containsMention(content, aliases)) {
+						console.error(`[abracadabra-mcp] skipped message on ${channel} — no @mention for ${aliases.join("|")}`);
+						return;
+					}
+					dispatchContent = stripMention(content, aliases) || content;
+				}
 			}
 			if (channel) {
 				const rootProvider = this._activeConnection?.provider;
@@ -20309,14 +20396,13 @@ var AbracadabraMCPServer = class {
 					timestamp: Math.floor(Date.now() / 1e3)
 				}));
 				this._lastChatChannel = channel;
-				this.sendTypingIndicator(channel);
-				this._startTypingInterval(channel);
 			}
+			this._beginTurn();
 			this.setAutoStatus("thinking");
 			await this._serverRef.notification({
 				method: "notifications/claude/channel",
 				params: {
-					content: data.content ?? "",
+					content: dispatchContent,
 					instructions: `You MUST use send_chat_message with channel="${channel ?? ""}" for ALL responses — both progress updates and final answers. The user CANNOT see plain text output; they only see messages sent via send_chat_message. When doing multi-step work, send brief status updates via send_chat_message (e.g. "Looking into that..." or "Found it, writing up results...") so the user knows you're working. Never output plain text as a substitute for send_chat_message.`,
 					meta: {
 						source: "abracadabra",
@@ -20347,13 +20433,35 @@ var AbracadabraMCPServer = class {
 		if (docId !== void 0) provider.awareness.setLocalStateField("docId", docId);
 		const context = status ? statusContext !== void 0 ? statusContext : this._lastChatChannel : null;
 		provider.awareness.setLocalStateField("statusContext", context ?? null);
-		if (!status) this._stopTypingInterval();
+		if (!status) {
+			this._stopTypingInterval();
+			provider.awareness.setLocalStateField("activeToolCall", null);
+			provider.awareness.setLocalStateField("turnId", null);
+			this._toolHistory = [];
+			provider.awareness.setLocalStateField("toolHistory", []);
+		}
 		if (status) this._statusClearTimer = setTimeout(() => {
 			provider.awareness.setLocalStateField("status", null);
 			provider.awareness.setLocalStateField("activeToolCall", null);
 			provider.awareness.setLocalStateField("statusContext", null);
+			provider.awareness.setLocalStateField("turnId", null);
+			this._toolHistory = [];
+			provider.awareness.setLocalStateField("toolHistory", []);
 			this._stopTypingInterval();
-		}, 3e4);
+		}, 1e4);
+	}
+	/**
+	* Start a new agent turn. Mints a fresh UUID and writes it to awareness so
+	* the dashboard can gate the incantation on "there is an active turn",
+	* decoupled from the (racier) status field. Called from chat arrival and
+	* ai:task dispatch right before `setAutoStatus('thinking')`.
+	*/
+	_beginTurn() {
+		const provider = this._activeConnection?.provider;
+		if (!provider) return;
+		this._toolHistory = [];
+		provider.awareness.setLocalStateField("toolHistory", []);
+		provider.awareness.setLocalStateField("turnId", crypto.randomUUID());
 	}
 	/** Re-send typing indicator every 2s so dashboard keeps showing it (expires at 3s). */
 	_startTypingInterval(channel) {
@@ -20371,10 +20479,28 @@ var AbracadabraMCPServer = class {
 	}
 	/**
 	* Broadcast which tool the agent is currently executing.
-	* Dashboard renders this as a ChatTool indicator.
+	*
+	* Renders as a ChatTool pill on the dashboard. On non-null calls, the tool
+	* is also appended to `toolHistory` (capped at TOOL_HISTORY_MAX) and written
+	* to awareness so the dashboard's inline trace can show the turn's recent
+	* activity. Tools do NOT clear (`setActiveToolCall(null)`) on completion —
+	* the pill stays until the next tool replaces it or `setAutoStatus(null)`
+	* flushes the turn. This keeps pills visible long enough to see.
 	*/
 	setActiveToolCall(toolCall) {
-		this._activeConnection?.provider?.awareness.setLocalStateField("activeToolCall", toolCall);
+		const provider = this._activeConnection?.provider;
+		if (!provider) return;
+		provider.awareness.setLocalStateField("activeToolCall", toolCall);
+		if (toolCall) {
+			this._toolHistory.push({
+				tool: toolCall.name,
+				target: toolCall.target,
+				ts: Date.now(),
+				channel: this._lastChatChannel
+			});
+			if (this._toolHistory.length > AbracadabraMCPServer.TOOL_HISTORY_MAX) this._toolHistory.splice(0, this._toolHistory.length - AbracadabraMCPServer.TOOL_HISTORY_MAX);
+			provider.awareness.setLocalStateField("toolHistory", [...this._toolHistory]);
+		}
 	}
 	/**
 	* Send a typing indicator to a chat channel.
@@ -20405,8 +20531,11 @@ var AbracadabraMCPServer = class {
 			conn.provider.awareness.setLocalStateField("status", null);
 			conn.provider.awareness.setLocalStateField("activeToolCall", null);
 			conn.provider.awareness.setLocalStateField("statusContext", null);
+			conn.provider.awareness.setLocalStateField("turnId", null);
+			conn.provider.awareness.setLocalStateField("toolHistory", []);
 			conn.provider.destroy();
 		}
+		this._toolHistory = [];
 		this._spaceConnections.clear();
 		this._activeConnection = null;
 		console.error("[abracadabra-mcp] Shutdown complete");
@@ -20431,6 +20560,724 @@ function docToSpaceMeta(doc) {
 	};
 }
 
+//#endregion
+//#region packages/mcp/src/converters/page-types.ts
+const PAGE_TYPES = {
+	doc: {
+		key: "doc",
+		label: "Document",
+		icon: "file-text",
+		description: "Rich text document with real-time collaboration",
+		core: true,
+		supportsChildren: true
+	},
+	kanban: {
+		key: "kanban",
+		label: "Kanban",
+		icon: "kanban",
+		description: "Drag-and-drop task board with columns and cards",
+		core: true,
+		supportsChildren: true,
+		childLabel: "Column",
+		grandchildLabel: "Card",
+		defaultMetaFields: [{
+			type: "select",
+			key: "kanbanColumnWidth",
+			options: [
+				"narrow",
+				"default",
+				"wide"
+			],
+			label: "Column Width"
+		}]
+	},
+	gallery: {
+		key: "gallery",
+		label: "Gallery",
+		icon: "images",
+		description: "Visual grid of items with rich content",
+		core: true,
+		supportsChildren: true,
+		childLabel: "Item",
+		metaSchema: [
+			{
+				type: "location",
+				latKey: "geoLat",
+				lngKey: "geoLng",
+				label: "Location"
+			},
+			{
+				type: "datetime",
+				key: "datetimeStart",
+				label: "Date"
+			},
+			{
+				type: "tags",
+				key: "tags",
+				label: "Tags"
+			},
+			{
+				type: "rating",
+				key: "rating",
+				max: 5,
+				label: "Rating"
+			},
+			{
+				type: "icon",
+				key: "icon",
+				label: "Icon"
+			},
+			{
+				type: "colorPreset",
+				key: "color",
+				presets: [
+					"#6366f1",
+					"#ec4899",
+					"#f97316",
+					"#22c55e",
+					"#3b82f6",
+					"#a855f7"
+				],
+				label: "Color"
+			}
+		],
+		defaultMetaFields: [
+			{
+				type: "number",
+				key: "galleryColumns",
+				min: 1,
+				max: 6,
+				step: 1,
+				label: "Columns"
+			},
+			{
+				type: "select",
+				key: "galleryAspect",
+				options: [
+					"square",
+					"4:3",
+					"3:2",
+					"16:9",
+					"free"
+				],
+				label: "Aspect Ratio"
+			},
+			{
+				type: "select",
+				key: "galleryCardStyle",
+				options: [
+					"default",
+					"compact",
+					"detailed"
+				],
+				label: "Card Style"
+			},
+			{
+				type: "toggle",
+				key: "galleryShowLabels",
+				label: "Show Labels"
+			},
+			{
+				type: "select",
+				key: "gallerySortBy",
+				options: [
+					"manual",
+					"date",
+					"name",
+					"rating"
+				],
+				label: "Sort"
+			}
+		]
+	},
+	table: {
+		key: "table",
+		label: "Table",
+		icon: "table",
+		description: "Collaborative spreadsheet with custom fields",
+		core: true,
+		supportsChildren: true,
+		childLabel: "Column",
+		grandchildLabel: "Row",
+		defaultMetaFields: [{
+			type: "select",
+			key: "tableMode",
+			options: ["hierarchy", "flat"],
+			label: "Mode"
+		}, {
+			type: "select",
+			key: "tableSortDir",
+			options: ["asc", "desc"],
+			label: "Sort Direction"
+		}]
+	},
+	outline: {
+		key: "outline",
+		label: "Outline",
+		icon: "list-tree",
+		description: "Hierarchical outline with keyboard navigation",
+		core: true,
+		supportsChildren: true,
+		childLabel: "Item",
+		defaultDepth: -1
+	},
+	checklist: {
+		key: "checklist",
+		label: "Checklist",
+		icon: "check-square",
+		description: "Collaborative checklist with sub-tasks, drag-and-drop, and due dates",
+		core: true,
+		supportsChildren: true,
+		childLabel: "Task",
+		defaultDepth: -1,
+		metaSchema: [
+			{
+				type: "toggle",
+				key: "checked",
+				label: "Done"
+			},
+			{
+				type: "select",
+				key: "priority",
+				options: [
+					"none",
+					"low",
+					"medium",
+					"high"
+				],
+				label: "Priority"
+			},
+			{
+				type: "date",
+				key: "dateEnd",
+				label: "Due date"
+			}
+		],
+		defaultMetaFields: [{
+			type: "select",
+			key: "checklistFilter",
+			options: [
+				"all",
+				"active",
+				"completed"
+			],
+			label: "Filter"
+		}, {
+			type: "select",
+			key: "checklistSort",
+			options: [
+				"manual",
+				"priority",
+				"due"
+			],
+			label: "Sort"
+		}]
+	},
+	graph: {
+		key: "graph",
+		label: "Graph",
+		icon: "git-fork",
+		description: "Force-directed knowledge graph — full document tree as nodes & edges",
+		core: true,
+		supportsChildren: true,
+		childLabel: "Node",
+		defaultMetaFields: [{
+			type: "toggle",
+			key: "showRefEdges",
+			label: "Show Ref Edges",
+			default: true
+		}]
+	},
+	timeline: {
+		key: "timeline",
+		label: "Timeline",
+		icon: "gantt-chart",
+		description: "Gantt-style project timeline with epics and tasks",
+		core: true,
+		supportsChildren: true,
+		childLabel: "Epic",
+		grandchildLabel: "Task",
+		metaSchema: [
+			{
+				type: "daterange",
+				startKey: "dateStart",
+				endKey: "dateEnd"
+			},
+			{
+				type: "slider",
+				key: "taskProgress",
+				min: 0,
+				max: 100,
+				label: "Progress"
+			},
+			{
+				type: "colorPreset",
+				key: "color",
+				presets: [
+					"#6366f1",
+					"#818cf8",
+					"#f97316",
+					"#22c55e",
+					"#3b82f6",
+					"#a855f7"
+				],
+				label: "Color"
+			}
+		]
+	},
+	calendar: {
+		key: "calendar",
+		label: "Calendar",
+		icon: "calendar",
+		description: "Event calendar with month, week, and day views",
+		core: true,
+		supportsChildren: true,
+		childLabel: "Event",
+		metaSchema: [
+			{
+				type: "datetimerange",
+				startKey: "datetimeStart",
+				endKey: "datetimeEnd",
+				allDayKey: "allDay"
+			},
+			{
+				type: "colorPreset",
+				key: "color",
+				presets: [
+					"#6366f1",
+					"#ec4899",
+					"#f97316",
+					"#22c55e",
+					"#3b82f6",
+					"#a855f7"
+				],
+				label: "Color"
+			},
+			{
+				type: "icon",
+				key: "icon",
+				label: "Icon"
+			}
+		],
+		defaultMetaFields: [
+			{
+				type: "select",
+				key: "calendarWeekStart",
+				options: ["sun", "mon"],
+				label: "Week Starts"
+			},
+			{
+				type: "select",
+				key: "calendarView",
+				options: [
+					"month",
+					"week",
+					"day"
+				],
+				label: "Default View"
+			},
+			{
+				type: "toggle",
+				key: "calendarShowWeekNumbers",
+				label: "Show Week Numbers"
+			}
+		]
+	},
+	map: {
+		key: "map",
+		label: "Map",
+		icon: "map",
+		description: "Collaborative world map with shared markers",
+		core: true,
+		supportsChildren: true,
+		childLabel: "Location",
+		defaultMetaFields: [{
+			type: "toggle",
+			key: "mapShowLabels",
+			label: "Show Labels",
+			default: true
+		}]
+	},
+	dashboard: {
+		key: "dashboard",
+		label: "Dashboard",
+		icon: "layout-dashboard",
+		description: "Arrange documents as draggable icons with optional widget views",
+		core: true,
+		supportsChildren: true,
+		childLabel: "Item"
+	},
+	call: {
+		key: "call",
+		label: "Call",
+		icon: "phone",
+		description: "Video call room with live audio and screen sharing",
+		core: true,
+		supportsChildren: false
+	},
+	chart: {
+		key: "chart",
+		label: "Chart",
+		icon: "bar-chart-3",
+		description: "Charts — manual data points or aggregation over document trees",
+		core: true,
+		supportsChildren: true,
+		childLabel: "Data Point",
+		grandchildLabel: "Data Point",
+		metaSchema: [
+			{
+				type: "number",
+				key: "number",
+				step: .01,
+				label: "Value"
+			},
+			{
+				type: "colorPreset",
+				key: "color",
+				presets: [
+					"#6366f1",
+					"#ec4899",
+					"#f97316",
+					"#22c55e",
+					"#3b82f6",
+					"#a855f7",
+					"#14b8a6",
+					"#eab308"
+				],
+				label: "Color"
+			},
+			{
+				type: "tags",
+				key: "tags",
+				label: "Tags"
+			}
+		],
+		defaultMetaFields: [
+			{
+				type: "select",
+				key: "chartType",
+				options: [
+					"bar",
+					"stacked bar",
+					"line",
+					"donut",
+					"treemap"
+				],
+				label: "Chart Type"
+			},
+			{
+				type: "select",
+				key: "chartMetric",
+				options: [
+					"value",
+					"type",
+					"tag",
+					"status",
+					"priority",
+					"activity",
+					"completion"
+				],
+				label: "Metric"
+			},
+			{
+				type: "select",
+				key: "chartColorScheme",
+				options: [
+					"default",
+					"warm",
+					"cool",
+					"mono"
+				],
+				label: "Colors"
+			},
+			{
+				type: "number",
+				key: "chartLimit",
+				min: 3,
+				max: 30,
+				step: 1,
+				label: "Max Items"
+			},
+			{
+				type: "toggle",
+				key: "chartShowLegend",
+				label: "Show Legend",
+				default: true
+			},
+			{
+				type: "toggle",
+				key: "chartShowValues",
+				label: "Show Values"
+			}
+		]
+	},
+	sheets: {
+		key: "sheets",
+		label: "Sheets",
+		icon: "grid-3x3",
+		description: "Spreadsheet — cells, formulas, and formatting in a collaborative grid",
+		core: true,
+		supportsChildren: true,
+		childLabel: "Column",
+		grandchildLabel: "Cell",
+		defaultMetaFields: [
+			{
+				type: "number",
+				key: "sheetsDefaultColWidth",
+				min: 40,
+				max: 500,
+				step: 10,
+				label: "Column Width"
+			},
+			{
+				type: "number",
+				key: "sheetsDefaultRowHeight",
+				min: 20,
+				max: 100,
+				step: 2,
+				label: "Row Height"
+			},
+			{
+				type: "toggle",
+				key: "sheetsShowGridlines",
+				label: "Gridlines"
+			}
+		]
+	},
+	slides: {
+		key: "slides",
+		label: "Slides",
+		icon: "presentation",
+		description: "Presentation slides with two-axis navigation",
+		core: true,
+		supportsChildren: true,
+		childLabel: "Slide",
+		grandchildLabel: "Sub-slide",
+		metaSchema: [{
+			type: "select",
+			key: "slidesTransition",
+			options: [
+				"none",
+				"fade",
+				"slide"
+			],
+			label: "Transition"
+		}, {
+			type: "colorPreset",
+			key: "color",
+			presets: [
+				"#6366f1",
+				"#ec4899",
+				"#f97316",
+				"#22c55e",
+				"#3b82f6",
+				"#a855f7"
+			],
+			label: "Accent"
+		}],
+		defaultMetaFields: [{
+			type: "select",
+			key: "slidesTheme",
+			options: ["dark", "light"],
+			label: "Theme"
+		}]
+	},
+	overview: {
+		key: "overview",
+		label: "Overview",
+		icon: "radar",
+		description: "Space home — activity, people, stats, and health at a glance",
+		core: true,
+		supportsChildren: true,
+		childLabel: "Page"
+	},
+	spatial: {
+		key: "spatial",
+		label: "Spatial",
+		icon: "box",
+		description: "3D scene with collaborative objects and real-time presence",
+		core: false,
+		plugin: "spatial",
+		supportsChildren: true,
+		childLabel: "Object",
+		grandchildLabel: "Part",
+		defaultDepth: -1,
+		metaSchema: [
+			{
+				type: "select",
+				key: "spShape",
+				options: [
+					"box",
+					"sphere",
+					"cylinder",
+					"cone",
+					"plane",
+					"torus",
+					"glb"
+				],
+				label: "Shape"
+			},
+			{
+				type: "colorPreset",
+				key: "color",
+				presets: [
+					"#6366f1",
+					"#ef4444",
+					"#22c55e",
+					"#3b82f6",
+					"#f97316",
+					"#a855f7",
+					"#ec4899",
+					"#14b8a6"
+				],
+				label: "Color"
+			},
+			{
+				type: "slider",
+				key: "spOpacity",
+				min: 0,
+				max: 100,
+				label: "Opacity"
+			},
+			{
+				type: "number",
+				key: "spX",
+				step: .1,
+				label: "X"
+			},
+			{
+				type: "number",
+				key: "spY",
+				step: .1,
+				label: "Y"
+			},
+			{
+				type: "number",
+				key: "spZ",
+				step: .1,
+				label: "Z"
+			},
+			{
+				type: "number",
+				key: "spRX",
+				min: -180,
+				max: 180,
+				step: 1,
+				label: "Rot X"
+			},
+			{
+				type: "number",
+				key: "spRY",
+				min: -180,
+				max: 180,
+				step: 1,
+				label: "Rot Y"
+			},
+			{
+				type: "number",
+				key: "spRZ",
+				min: -180,
+				max: 180,
+				step: 1,
+				label: "Rot Z"
+			},
+			{
+				type: "number",
+				key: "spSX",
+				min: .01,
+				max: 100,
+				step: .1,
+				label: "Scale X"
+			},
+			{
+				type: "number",
+				key: "spSY",
+				min: .01,
+				max: 100,
+				step: .1,
+				label: "Scale Y"
+			},
+			{
+				type: "number",
+				key: "spSZ",
+				min: .01,
+				max: 100,
+				step: .1,
+				label: "Scale Z"
+			}
+		],
+		defaultMetaFields: [{
+			type: "toggle",
+			key: "spatialGridVisible",
+			label: "Show Grid",
+			default: true
+		}]
+	},
+	media: {
+		key: "media",
+		label: "Media",
+		icon: "disc-3",
+		description: "Media player with synced listening and playlists",
+		core: false,
+		plugin: "media",
+		supportsChildren: true,
+		childLabel: "Track",
+		defaultDepth: -1,
+		metaSchema: [{
+			type: "tags",
+			key: "tags",
+			label: "Tags"
+		}],
+		defaultMetaFields: [{
+			type: "select",
+			key: "mediaRepeat",
+			options: [
+				"off",
+				"all",
+				"one"
+			],
+			label: "Repeat"
+		}, {
+			type: "toggle",
+			key: "mediaShuffle",
+			label: "Shuffle"
+		}]
+	},
+	coder: {
+		key: "coder",
+		label: "Coder",
+		icon: "code-2",
+		description: "Collaborative multi-file coding environment",
+		core: false,
+		plugin: "coder",
+		supportsChildren: true,
+		childLabel: "File",
+		defaultDepth: -1,
+		metaSchema: [{
+			type: "select",
+			key: "fileType",
+			options: [
+				"vue",
+				"ts",
+				"js",
+				"css",
+				"json",
+				"folder"
+			],
+			label: "Type"
+		}, {
+			type: "toggle",
+			key: "entry",
+			label: "Entry Point"
+		}]
+	}
+};
+const TYPE_ALIASES = { desktop: "dashboard" };
+function resolvePageType(key) {
+	if (!key) return void 0;
+	return PAGE_TYPES[TYPE_ALIASES[key] ?? key];
+}
+
 //#endregion
 //#region packages/mcp/src/tools/tree.ts
 /**
@@ -20504,16 +21351,12 @@ function registerTreeTools(mcp, server) {
 		server.setAutoStatus("reading");
 		server.setActiveToolCall({ name: "list_documents" });
 		const treeMap = server.getTreeMap();
-		if (!treeMap) {
-			server.setActiveToolCall(null);
-			return { content: [{
-				type: "text",
-				text: "Not connected"
-			}] };
-		}
+		if (!treeMap) return { content: [{
+			type: "text",
+			text: "Not connected"
+		}] };
 		const targetId = normalizeRootId(parentId, server);
 		const children = childrenOf$1(readEntries$1(treeMap), targetId);
-		server.setActiveToolCall(null);
 		return { content: [{
 			type: "text",
 			text: JSON.stringify(children, null, 2)
@@ -20526,17 +21369,13 @@ function registerTreeTools(mcp, server) {
 		server.setAutoStatus("reading");
 		server.setActiveToolCall({ name: "get_document_tree" });
 		const treeMap = server.getTreeMap();
-		if (!treeMap) {
-			server.setActiveToolCall(null);
-			return { content: [{
-				type: "text",
-				text: "Not connected"
-			}] };
-		}
+		if (!treeMap) return { content: [{
+			type: "text",
+			text: "Not connected"
+		}] };
 		const targetId = normalizeRootId(rootId, server);
 		const maxDepth = depth ?? 3;
 		const tree = buildTree$1(readEntries$1(treeMap), targetId, maxDepth);
-		server.setActiveToolCall(null);
 		return { content: [{
 			type: "text",
 			text: JSON.stringify(tree, null, 2)
@@ -20552,13 +21391,10 @@ function registerTreeTools(mcp, server) {
 			target: query
 		});
 		const treeMap = server.getTreeMap();
-		if (!treeMap) {
-			server.setActiveToolCall(null);
-			return { content: [{
-				type: "text",
-				text: "Not connected"
-			}] };
-		}
+		if (!treeMap) return { content: [{
+			type: "text",
+			text: "Not connected"
+		}] };
 		const entries = readEntries$1(treeMap);
 		const lowerQuery = query.toLowerCase();
 		const normalizedRoot = normalizeRootId(rootId, server);
@@ -20583,7 +21419,6 @@ function registerTreeTools(mcp, server) {
 				path
 			};
 		});
-		server.setActiveToolCall(null);
 		if (results.length === 0) return { content: [{
 			type: "text",
 			text: `No documents found matching "${query}". Try get_document_tree to see the full hierarchy.`
@@ -20596,8 +21431,8 @@ function registerTreeTools(mcp, server) {
 	mcp.tool("create_document", "Create a new document in the tree. Returns the new document ID.", {
 		parentId: z.string().optional().describe("Parent document ID. Omit for top-level pages. Use a document ID for nested/child pages."),
 		label: z.string().describe("Display name / title for the document."),
-		type: z.string().optional().describe("Page type — sets how this document renders. \"doc\" (rich text), \"kanban\" (columns → cards), \"table\" (columns → rows with custom fields), \"calendar\" (events with datetimeStart/End), \"timeline\" (epics → tasks with dateStart/End + taskProgress), \"checklist\" (tasks with checked/priority, unlimited nesting), \"outline\" (nested items, unlimited depth), \"gallery\" (visual grid with covers/ratings), \"map\" (markers/lines with geoLat/geoLng), \"graph\" (force-directed knowledge graph), \"dashboard\" (positioned widgets with deskX/deskY/deskMode), \"spatial\" (3D scene with spShape/spX/spY/spZ), \"media\" (audio/video player with playlists), \"slides\" (presentation with transitions), \"chart\" (bar/line/donut/treemap from data points or aggregation), \"sheets\" (spreadsheet with formulas and formatting), \"overview\" (space home — activity and stats), \"call\" (video call room, no children). Omit to inherit parent view. Only set on the parent page, NEVER on child items."),
-		meta: z.record(z.unknown()).optional().describe("Initial metadata (PageMeta fields: color as hex string, icon as Lucide kebab-case name like \"star\"/\"code-2\"/\"users\" — never emoji, dateStart, dateEnd, priority 0-4, tags array, etc). Omit icon entirely to use page type default.")
+		type: z.string().optional().describe("Page type — sets how this document renders. Core types (always available): \"doc\" (rich text), \"kanban\" (columns → cards), \"table\" (columns → rows, positional), \"calendar\" (events with datetimeStart/End), \"timeline\" (epics → tasks with dateStart/End + taskProgress), \"checklist\" (tasks with checked/priority, unlimited nesting), \"outline\" (nested items, unlimited depth), \"gallery\" (visual grid with covers/ratings), \"map\" (markers/lines with geoLat/geoLng), \"graph\" (force-directed knowledge graph), \"dashboard\" (positioned widgets with deskX/deskY/deskMode), \"slides\" (slides → sub-slides with transitions), \"chart\" (bar/stacked bar/line/donut/treemap from data points or aggregation), \"sheets\" (spreadsheet with formulas and formatting), \"overview\" (space home — activity and stats), \"call\" (video call room, no children). Plugin types (require plugin enabled on the server): \"spatial\" (3D scene with spShape/spX/spY/spZ + universal color, plugin: spatial), \"media\" (audio/video player with playlists, plugin: media), \"coder\" (collaborative multi-file coding env with fileType/entry, plugin: coder). Alias: \"desktop\" → \"dashboard\". Omit to inherit parent view. Only set on the parent page, NEVER on child items."),
+		meta: z.record(z.string(), z.unknown()).optional().describe("Initial metadata (PageMeta fields: color as hex string, icon as Lucide kebab-case name like \"star\"/\"code-2\"/\"users\" — never emoji, dateStart, dateEnd, priority 0-4, tags array, etc). Omit icon entirely to use page type default.")
 	}, async ({ parentId, label, type, meta }) => {
 		server.setAutoStatus("creating");
 		server.setActiveToolCall({
@@ -20606,13 +21441,10 @@ function registerTreeTools(mcp, server) {
 		});
 		const treeMap = server.getTreeMap();
 		const rootDoc = server.rootDocument;
-		if (!treeMap || !rootDoc) {
-			server.setActiveToolCall(null);
-			return { content: [{
-				type: "text",
-				text: "Not connected"
-			}] };
-		}
+		if (!treeMap || !rootDoc) return { content: [{
+			type: "text",
+			text: "Not connected"
+		}] };
 		const id = crypto.randomUUID();
 		const normalizedParent = normalizeRootId(parentId, server);
 		const now = Date.now();
@@ -20628,7 +21460,6 @@ function registerTreeTools(mcp, server) {
 			});
 		});
 		server.setFocusedDoc(id);
-		server.setActiveToolCall(null);
 		return { content: [{
 			type: "text",
 			text: JSON.stringify({
@@ -20649,28 +21480,21 @@ function registerTreeTools(mcp, server) {
 			target: id
 		});
 		const treeMap = server.getTreeMap();
-		if (!treeMap) {
-			server.setActiveToolCall(null);
-			return { content: [{
-				type: "text",
-				text: "Not connected"
-			}] };
-		}
+		if (!treeMap) return { content: [{
+			type: "text",
+			text: "Not connected"
+		}] };
 		const raw = treeMap.get(id);
-		if (!raw) {
-			server.setActiveToolCall(null);
-			return { content: [{
-				type: "text",
-				text: `Document ${id} not found`
-			}] };
-		}
+		if (!raw) return { content: [{
+			type: "text",
+			text: `Document ${id} not found`
+		}] };
 		const entry = toPlain(raw);
 		treeMap.set(id, {
 			...entry,
 			label,
 			updatedAt: Date.now()
 		});
-		server.setActiveToolCall(null);
 		return { content: [{
 			type: "text",
 			text: `Renamed to "${label}"`
@@ -20687,21 +21511,15 @@ function registerTreeTools(mcp, server) {
 			target: id
 		});
 		const treeMap = server.getTreeMap();
-		if (!treeMap) {
-			server.setActiveToolCall(null);
-			return { content: [{
-				type: "text",
-				text: "Not connected"
-			}] };
-		}
+		if (!treeMap) return { content: [{
+			type: "text",
+			text: "Not connected"
+		}] };
 		const raw = treeMap.get(id);
-		if (!raw) {
-			server.setActiveToolCall(null);
-			return { content: [{
-				type: "text",
-				text: `Document ${id} not found`
-			}] };
-		}
+		if (!raw) return { content: [{
+			type: "text",
+			text: `Document ${id} not found`
+		}] };
 		const entry = toPlain(raw);
 		treeMap.set(id, {
 			...entry,
@@ -20709,7 +21527,6 @@ function registerTreeTools(mcp, server) {
 			order: order ?? Date.now(),
 			updatedAt: Date.now()
 		});
-		server.setActiveToolCall(null);
 		return { content: [{
 			type: "text",
 			text: `Moved ${id} to parent ${newParentId}`
@@ -20724,13 +21541,10 @@ function registerTreeTools(mcp, server) {
 		const treeMap = server.getTreeMap();
 		const trashMap = server.getTrashMap();
 		const rootDoc = server.rootDocument;
-		if (!treeMap || !trashMap || !rootDoc) {
-			server.setActiveToolCall(null);
-			return { content: [{
-				type: "text",
-				text: "Not connected"
-			}] };
-		}
+		if (!treeMap || !trashMap || !rootDoc) return { content: [{
+			type: "text",
+			text: "Not connected"
+		}] };
 		const toDelete = [id, ...descendantsOf(readEntries$1(treeMap), id).map((e) => e.id)];
 		const now = Date.now();
 		rootDoc.transact(() => {
@@ -20749,7 +21563,6 @@ function registerTreeTools(mcp, server) {
 				treeMap.delete(nid);
 			}
 		});
-		server.setActiveToolCall(null);
 		return { content: [{
 			type: "text",
 			text: `Deleted ${toDelete.length} document(s)`
@@ -20757,7 +21570,7 @@ function registerTreeTools(mcp, server) {
 	});
 	mcp.tool("change_document_type", "Change the page type view of a document (data is preserved).", {
 		id: z.string().describe("Document ID."),
-		type: z.string().describe("New page type: \"doc\", \"kanban\", \"table\", \"calendar\", \"timeline\", \"checklist\", \"outline\", \"gallery\", \"map\", \"graph\", \"dashboard\", \"spatial\", \"media\", \"slides\", \"chart\", \"sheets\", \"overview\", \"call\".")
+		type: z.string().describe("New page type. Core: \"doc\", \"kanban\", \"table\", \"calendar\", \"timeline\", \"checklist\", \"outline\", \"gallery\", \"map\", \"graph\", \"dashboard\", \"slides\", \"chart\", \"sheets\", \"overview\", \"call\". Plugin (require plugin enabled): \"spatial\", \"media\", \"coder\". Switching preserves the tree — children, labels, and meta are all retained; only the view changes.")
 	}, async ({ id, type }) => {
 		server.setAutoStatus("writing");
 		server.setActiveToolCall({
@@ -20765,28 +21578,21 @@ function registerTreeTools(mcp, server) {
 			target: id
 		});
 		const treeMap = server.getTreeMap();
-		if (!treeMap) {
-			server.setActiveToolCall(null);
-			return { content: [{
-				type: "text",
-				text: "Not connected"
-			}] };
-		}
+		if (!treeMap) return { content: [{
+			type: "text",
+			text: "Not connected"
+		}] };
 		const raw = treeMap.get(id);
-		if (!raw) {
-			server.setActiveToolCall(null);
-			return { content: [{
-				type: "text",
-				text: `Document ${id} not found`
-			}] };
-		}
+		if (!raw) return { content: [{
+			type: "text",
+			text: `Document ${id} not found`
+		}] };
 		const entry = toPlain(raw);
 		treeMap.set(id, {
 			...entry,
 			type,
 			updatedAt: Date.now()
 		});
-		server.setActiveToolCall(null);
 		return { content: [{
 			type: "text",
 			text: `Changed type to "${type}"`
@@ -20842,6 +21648,27 @@ function registerTreeTools(mcp, server) {
 			}, null, 2)
 		}] };
 	});
+	mcp.tool("list_page_types", "Enumerate all known Abracadabra page types with their metadata schemas. Returns an array of { key, label, icon, description, core, plugin, supportsChildren, childLabel, grandchildLabel, defaultDepth, metaSchema, defaultMetaFields }. `metaSchema` describes fields that apply to DESCENDANTS (children, grandchildren, ...) of a page of this type. `defaultMetaFields` are view-config fields on the page doc itself. Plugin types (core: false) require the named plugin to be enabled on the server. Use this to discover what meta keys a given renderer supports instead of guessing.", { key: z.string().optional().describe("Filter to a single type by key (e.g. \"kanban\", \"calendar\"). Aliases are resolved (e.g. \"desktop\" → \"dashboard\"). Omit to list all types.") }, async ({ key }) => {
+		if (key) {
+			const resolved = resolvePageType(key);
+			if (!resolved) return { content: [{
+				type: "text",
+				text: `Unknown page type "${key}". Call list_page_types with no args to see all types.`
+			}] };
+			return { content: [{
+				type: "text",
+				text: JSON.stringify(resolved, null, 2)
+			}] };
+		}
+		const all = Object.values(PAGE_TYPES);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({
+				types: all,
+				aliases: TYPE_ALIASES
+			}, null, 2)
+		}] };
+	});
 }
 
 //#endregion
@@ -22018,7 +22845,6 @@ function registerContentTools(mcp, server) {
 				});
 				children.sort((a, b) => (treeMap.get(a.id)?.order ?? 0) - (treeMap.get(b.id)?.order ?? 0));
 			}
-			server.setActiveToolCall(null);
 			const result = {
 				label,
 				type,
@@ -22031,7 +22857,6 @@ function registerContentTools(mcp, server) {
 				text: JSON.stringify(result, null, 2)
 			}] };
 		} catch (error) {
-			server.setActiveToolCall(null);
 			return {
 				content: [{
 					type: "text",
@@ -22081,13 +22906,11 @@ function registerContentTools(mcp, server) {
 			populateYDocFromMarkdown(fragment, body || markdown, title || "Untitled");
 			server.setFocusedDoc(docId);
 			server.setDocCursor(docId, fragment.length);
-			server.setActiveToolCall(null);
 			return { content: [{
 				type: "text",
 				text: `Document ${docId} updated (${writeMode} mode)`
 			}] };
 		} catch (error) {
-			server.setActiveToolCall(null);
 			return {
 				content: [{
 					type: "text",
@@ -22109,22 +22932,15 @@ function registerMetaTools(mcp, server) {
 			target: docId
 		});
 		const treeMap = server.getTreeMap();
-		if (!treeMap) {
-			server.setActiveToolCall(null);
-			return { content: [{
-				type: "text",
-				text: "Not connected"
-			}] };
-		}
+		if (!treeMap) return { content: [{
+			type: "text",
+			text: "Not connected"
+		}] };
 		const entry = treeMap.get(docId);
-		if (!entry) {
-			server.setActiveToolCall(null);
-			return { content: [{
-				type: "text",
-				text: `Document ${docId} not found`
-			}] };
-		}
-		server.setActiveToolCall(null);
+		if (!entry) return { content: [{
+			type: "text",
+			text: `Document ${docId} not found`
+		}] };
 		return { content: [{
 			type: "text",
 			text: JSON.stringify({
@@ -22137,7 +22953,7 @@ function registerMetaTools(mcp, server) {
 	});
 	mcp.tool("update_metadata", "Update metadata fields on a document. Merges the provided fields into existing metadata.", {
 		docId: z.string().describe("Document ID."),
-		meta: z.record(z.unknown()).describe("Metadata fields to update (merged with existing). Universal keys: color (hex), icon (Lucide kebab-case — NEVER emoji), dateStart/dateEnd, datetimeStart/datetimeEnd, allDay, tags (string[]), checked (bool), priority (0=none,1=low,2=med,3=high,4=urgent), status, rating (0-5), url, email, phone, number, unit, subtitle, note, taskProgress (0-100), members ({id,label}[]), coverUploadId. Geo/Map: geoType (\"marker\"|\"line\"|\"measure\"), geoLat, geoLng, geoDescription. Spatial 3D: spShape (\"box\"|\"sphere\"|\"cylinder\"|\"cone\"|\"plane\"|\"torus\"|\"glb\"), spX/spY/spZ, spRX/spRY/spRZ, spSX/spSY/spSZ, spColor, spOpacity (0-100). Dashboard: deskX, deskY, deskZ, deskMode (\"icon\"|\"widget-sm\"|\"widget-lg\"). Slides: slidesTransition (\"none\"|\"fade\"|\"slide\"), slidesTheme (\"dark\"|\"light\"). Chart: chartType (\"bar\"|\"stacked bar\"|\"line\"|\"donut\"|\"treemap\"), chartMetric, chartColorScheme, chartLimit, chartShowLegend, chartShowValues. Sheets: sheetsDefaultColWidth, sheetsDefaultRowHeight, sheetsShowGridlines, sheetsFreezeRows, sheetsFreezeCols. Cell formatting: bold, italic, textColor, bgColor, align, formula. Renderer config (on the page doc itself): kanbanColumnWidth, galleryColumns, galleryAspect, galleryCardStyle, galleryShowLabels, gallerySortBy, calendarView, calendarWeekStart, calendarShowWeekNumbers, tableMode, tableSortDir, checklistFilter, checklistSort, mapShowLabels, spatialGridVisible, showRefEdges, mediaRepeat, mediaShuffle. Set a key to null to clear it.")
+		meta: z.record(z.string(), z.unknown()).describe("Metadata fields to update (merged with existing). Universal keys: color (hex), icon (Lucide kebab-case — NEVER emoji), dateStart/dateEnd, datetimeStart/datetimeEnd, allDay, timeStart/timeEnd, tags (string[]), checked (bool), priority (0=none,1=low,2=med,3=high,4=urgent), status, rating (0-5), url, email, phone, number, unit, subtitle, note, taskProgress (0-100), members ({id,label}[]), coverUploadId, coverDocId, dateTaken. Geo/Map (children): geoType (\"marker\"|\"line\"|\"measure\"), geoLat, geoLng, geoDescription. Spatial 3D (children, plugin: spatial): spShape (\"box\"|\"sphere\"|\"cylinder\"|\"cone\"|\"plane\"|\"torus\"|\"glb\"), spX/spY/spZ, spRX/spRY/spRZ (deg), spSX/spSY/spSZ (scale), spOpacity (0-100), spModelUploadId, spModelDocId — spatial uses the universal `color` key, NOT spColor. Dashboard (children): deskX, deskY, deskZ, deskMode (\"icon\"|\"widget-sm\"|\"widget-lg\"). Mindmap-layout (children): mmX, mmY. Graph-layout (children): graphX, graphY, graphPinned. Slides (children): slidesTransition (\"none\"|\"fade\"|\"slide\"). Coder (children, plugin: coder): fileType (\"vue\"|\"ts\"|\"js\"|\"css\"|\"json\"|\"folder\"), entry (bool). Cell formatting (sheets cells): bold, italic, textColor, bgColor, align (\"left\"|\"center\"|\"right\"), formula. Renderer config (on the PAGE doc itself, not children): kanbanColumnWidth (\"narrow\"|\"default\"|\"wide\"), galleryColumns (1-6), galleryAspect (\"square\"|\"4:3\"|\"3:2\"|\"16:9\"|\"free\"), galleryCardStyle (\"default\"|\"compact\"|\"detailed\"), galleryShowLabels, gallerySortBy (\"manual\"|\"date\"|\"name\"|\"rating\"), calendarView (\"month\"|\"week\"|\"day\"), calendarWeekStart (\"sun\"|\"mon\"), calendarShowWeekNumbers, tableMode (\"hierarchy\"|\"flat\"), tableSortKey, tableSortDir (\"asc\"|\"desc\"), timelineZoom (\"week\"|\"month\"|\"quarter\"), timelinePixelsPerDay, timelineCenterDate (ISO date), checklistFilter (\"all\"|\"active\"|\"completed\"), checklistSort (\"manual\"|\"priority\"|\"due\"), mapShowLabels, graphSpacing (\"compact\"|\"default\"|\"spacious\"), graphShowLabels, graphEdgeThickness (\"thin\"|\"normal\"|\"thick\"), showRefEdges, mmSpacing, spatialGridVisible, slidesTheme (\"dark\"|\"light\"), chartType (\"bar\"|\"stacked bar\"|\"line\"|\"donut\"|\"treemap\"), chartMetric (\"value\"|\"type\"|\"tag\"|\"status\"|\"priority\"|\"activity\"|\"completion\"), chartColorScheme (\"default\"|\"warm\"|\"cool\"|\"mono\"), chartLimit (3-30), chartShowLegend, chartShowValues, sheetsDefaultColWidth (40-500), sheetsDefaultRowHeight (20-100), sheetsShowGridlines, sheetsFreezeRows, sheetsFreezeCols, mediaRepeat (\"off\"|\"all\"|\"one\"), mediaShuffle. Set a key to null to clear it.")
 	}, async ({ docId, meta }) => {
 		server.setAutoStatus("writing", docId);
 		server.setActiveToolCall({
@@ -22145,21 +22961,15 @@ function registerMetaTools(mcp, server) {
 			target: docId
 		});
 		const treeMap = server.getTreeMap();
-		if (!treeMap) {
-			server.setActiveToolCall(null);
-			return { content: [{
-				type: "text",
-				text: "Not connected"
-			}] };
-		}
+		if (!treeMap) return { content: [{
+			type: "text",
+			text: "Not connected"
+		}] };
 		const entry = treeMap.get(docId);
-		if (!entry) {
-			server.setActiveToolCall(null);
-			return { content: [{
-				type: "text",
-				text: `Document ${docId} not found`
-			}] };
-		}
+		if (!entry) return { content: [{
+			type: "text",
+			text: `Document ${docId} not found`
+		}] };
 		treeMap.set(docId, {
 			...entry,
 			meta: {
@@ -22168,7 +22978,6 @@ function registerMetaTools(mcp, server) {
 			},
 			updatedAt: Date.now()
 		});
-		server.setActiveToolCall(null);
 		return { content: [{
 			type: "text",
 			text: `Metadata updated for ${docId}`
@@ -22183,6 +22992,11 @@ function registerMetaTools(mcp, server) {
 */
 function registerFileTools(mcp, server) {
 	mcp.tool("list_uploads", "List file attachments for a document.", { docId: z.string().describe("Document ID.") }, async ({ docId }) => {
+		server.setAutoStatus("reading", docId);
+		server.setActiveToolCall({
+			name: "list_uploads",
+			target: docId
+		});
 		try {
 			const uploads = await server.client.listUploads(docId);
 			return { content: [{
@@ -22204,6 +23018,11 @@ function registerFileTools(mcp, server) {
 		filePath: z.string().describe("Absolute path to the local file to upload."),
 		filename: z.string().optional().describe("Override filename (defaults to basename of filePath).")
 	}, async ({ docId, filePath, filename }) => {
+		server.setAutoStatus("uploading", docId);
+		server.setActiveToolCall({
+			name: "upload_file",
+			target: path.basename(filePath)
+		});
 		try {
 			const resolvedPath = path.resolve(filePath);
 			const data = fs.readFileSync(resolvedPath);
@@ -22229,6 +23048,11 @@ function registerFileTools(mcp, server) {
 		uploadId: z.string().describe("Upload ID to download."),
 		saveTo: z.string().describe("Absolute local file path to save the download.")
 	}, async ({ docId, uploadId, saveTo }) => {
+		server.setAutoStatus("reading", docId);
+		server.setActiveToolCall({
+			name: "download_file",
+			target: path.basename(saveTo)
+		});
 		try {
 			const blob = await server.client.getUpload(docId, uploadId);
 			const buffer = Buffer.from(await blob.arrayBuffer());
@@ -22252,6 +23076,11 @@ function registerFileTools(mcp, server) {
 		docId: z.string().describe("Document ID."),
 		uploadId: z.string().describe("Upload ID to delete.")
 	}, async ({ docId, uploadId }) => {
+		server.setAutoStatus("writing", docId);
+		server.setActiveToolCall({
+			name: "delete_file",
+			target: uploadId
+		});
 		try {
 			await server.client.deleteUpload(docId, uploadId);
 			return { content: [{
@@ -22293,6 +23122,10 @@ function registerAwarenessTools(mcp, server) {
 		docId: z.string().describe("Document ID to set awareness on."),
 		fields: z.record(z.string(), z.unknown()).describe("Key-value pairs to set on the child document's awareness state. Use namespaced keys like \"kanban:hovering\", \"table:editing\", \"slides:viewing\", \"outline:editing\", \"calendar:focused\", \"gallery:focused\", \"timeline:focused\", \"graph:focused\", \"map:focused\", \"doc:scroll\". Set a key to null to clear it.")
 	}, async ({ docId, fields }) => {
+		server.setActiveToolCall({
+			name: "set_doc_awareness",
+			target: docId
+		});
 		try {
 			const provider = await server.getChildProvider(docId);
 			for (const [key, value] of Object.entries(fields)) provider.awareness.setLocalStateField(key, value ?? null);
@@ -22311,6 +23144,7 @@ function registerAwarenessTools(mcp, server) {
 		}
 	});
 	mcp.tool("poll_inbox", "Check the \"AI Inbox\" document for pending instructions from humans. Returns the inbox content and any pending task sub-documents. Create the inbox as a doc called \"AI Inbox\" under the hub doc if it does not exist yet. Note: channel-based watching via watch_chat is preferred for real-time use.", {}, async () => {
+		server.setActiveToolCall({ name: "poll_inbox" });
 		try {
 			const treeMap = server.getTreeMap();
 			const rootDocId = server.rootDocId;
@@ -22357,6 +23191,10 @@ function registerAwarenessTools(mcp, server) {
 		}
 	});
 	mcp.tool("list_connected_users", "List all connected users and their awareness state. Shows who is online and what they are doing.", { docId: z.string().optional().describe("If provided, list users connected to this specific document. Otherwise lists users from root awareness.") }, async ({ docId }) => {
+		server.setActiveToolCall({
+			name: "list_connected_users",
+			target: docId
+		});
 		try {
 			let awareness;
 			if (docId) awareness = (await server.getChildProvider(docId)).awareness;
@@ -22401,16 +23239,13 @@ function registerChannelTools(mcp, server) {
 			});
 			const treeMap = server.getTreeMap();
 			const rootDoc = server.rootDocument;
-			if (!treeMap || !rootDoc) {
-				server.setActiveToolCall(null);
-				return {
-					content: [{
-						type: "text",
-						text: "Not connected"
-					}],
-					isError: true
-				};
-			}
+			if (!treeMap || !rootDoc) return {
+				content: [{
+					type: "text",
+					text: "Not connected"
+				}],
+				isError: true
+			};
 			const label = `AI Reply — ${(/* @__PURE__ */ new Date()).toISOString().replace("T", " ").slice(0, 19)}: ${text.slice(0, 40).replace(/\n/g, " ")}`;
 			const replyId = crypto.randomUUID();
 			const now = Date.now();
@@ -22426,7 +23261,6 @@ function registerChannelTools(mcp, server) {
 			});
 			populateYDocFromMarkdown((await server.getChildProvider(replyId)).document, text);
 			if (task_id) server.clearAiTask(task_id);
-			server.setActiveToolCall(null);
 			return { content: [{
 				type: "text",
 				text: JSON.stringify({
@@ -22435,7 +23269,6 @@ function registerChannelTools(mcp, server) {
 				})
 			}] };
 		} catch (error) {
-			server.setActiveToolCall(null);
 			return {
 				content: [{
 					type: "text",
@@ -22458,14 +23291,15 @@ function registerChannelTools(mcp, server) {
 				}],
 				isError: true
 			};
+			const normalized = text.replace(/\\r\\n/g, "\n").replace(/\\n/g, "\n").replace(/\\t/g, "	").replace(/\\r/g, "\n");
+			server.setAutoStatus(null);
+			server.sendTypingIndicator(channel);
 			rootProvider.sendStateless(JSON.stringify({
 				type: "chat:send",
 				channel,
-				content: text,
+				content: normalized,
 				sender_name: server.agentName
 			}));
-			server.setAutoStatus(null);
-			server.setActiveToolCall(null);
 			return { content: [{
 				type: "text",
 				text: `Sent to ${channel}`
@@ -22620,16 +23454,13 @@ function registerSvgTools(mcp, server) {
 				target: docId
 			});
 			const cleanSvg = sanitizeSvg(svg);
-			if (!cleanSvg) {
-				server.setActiveToolCall(null);
-				return {
-					content: [{
-						type: "text",
-						text: "Error: SVG markup was empty or entirely stripped by sanitizer."
-					}],
-					isError: true
-				};
-			}
+			if (!cleanSvg) return {
+				content: [{
+					type: "text",
+					text: "Error: SVG markup was empty or entirely stripped by sanitizer."
+				}],
+				isError: true
+			};
 			const doc = (await server.getChildProvider(docId)).document;
 			const fragment = doc.getXmlFragment("default");
 			doc.transact(() => {
@@ -22640,13 +23471,11 @@ function registerSvgTools(mcp, server) {
 				fragment.insert(insertPos, [el]);
 			});
 			server.setFocusedDoc(docId);
-			server.setActiveToolCall(null);
 			return { content: [{
 				type: "text",
 				text: `SVG inserted into document ${docId}${title ? ` ("${title}")` : ""}`
 			}] };
 		} catch (error) {
-			server.setActiveToolCall(null);
 			return {
 				content: [{
 					type: "text",
@@ -22704,24 +23533,38 @@ If you are adding content to an existing space, call \`get_document_tree(rootId:
 
 ## Page Types Reference
 
+### Core Types (always available)
+
 | Type | Children Are | Grandchildren Are | Depth | Key Meta on Children |
 |------|-------------|-------------------|-------|---------------------|
 | **doc** | Sub-documents | Sub-sub-documents | ∞ | — |
 | **kanban** | Columns | Cards | 2 | color, icon on cards |
 | **table** | Columns | Cells (positional rows) | 2 | — |
-| **calendar** | Events | — | 1 | datetimeStart, datetimeEnd, allDay, color |
+| **calendar** | Events | — | 1 | datetimeStart, datetimeEnd, allDay, color, icon |
 | **timeline** | Epics | Tasks | 2 | dateStart, dateEnd, taskProgress, color |
 | **checklist** | Tasks | Sub-tasks | ∞ | checked, priority, dateEnd |
 | **outline** | Items | Sub-items | ∞ | — |
-| **mindmap** | Central nodes | Branches | ∞ | mmX, mmY |
 | **graph** | Nodes | — | 1 | graphX, graphY, graphPinned, color |
-| **gallery** | Items | — | 1 | geoLat, geoLng, datetimeStart, tags |
+| **gallery** | Items | — | 1 | geoLat, geoLng, datetimeStart, tags, rating, icon, color |
 | **map** | Markers/Lines | Points (for lines) | 2 | geoType, geoLat, geoLng, icon, color |
-| **dashboard** | Items | — | 1 | deskX, deskY, deskMode |
-| **spatial** | Objects | Sub-parts | ∞ | spShape, spX/Y/Z, spColor, spOpacity |
-| **media** | Tracks | — | 1 | tags |
-| **slides** | Slides | — | 1 | — |
-| **whiteboard** | Objects | — | 1 | wbX, wbY, wbW, wbH |
+| **slides** | Slides | Sub-slides | 2 | slidesTransition, color |
+| **dashboard** | Items | — | 1 | deskX, deskY, deskZ, deskMode |
+| **chart** | Data points | Data points | 2 | number (value), color, tags |
+| **sheets** | Columns | Cells | 2 | formula, bold, italic, textColor, bgColor, align |
+| **overview** | Pages | — | 1 | — |
+| **call** | — (no children) | — | 0 | — |
+
+Alias: \`desktop\` → \`dashboard\`.
+
+### Plugin Types (require plugin enabled on the server)
+
+| Type | Plugin | Children Are | Grandchildren Are | Depth | Key Meta on Children |
+|------|--------|-------------|-------------------|-------|---------------------|
+| **spatial** | spatial | Objects | Sub-parts | ∞ | spShape, spX/Y/Z, spRX/RY/RZ, spSX/SY/SZ, color, spOpacity |
+| **media** | media | Tracks | — | ∞ | tags |
+| **coder** | coder | Files/Folders | — | ∞ | fileType, entry |
+
+> Spatial uses the universal \`color\` key for object color — there is no \`spColor\`.
 
 ---
 
@@ -22794,18 +23637,65 @@ If you are adding content to an existing space, call \`get_document_tree(rootId:
 4. Modes: \`"icon"\` (small), \`"widget-sm"\` (240×180), \`"widget-lg"\` (400×320)
 5. Grid uses 80px cells
 
-**Spatial (3D scene):**
+**Spatial (3D scene)** *(requires spatial plugin):*
 1. \`create_document(parentId, "3D Scene", "spatial")\`
 2. Create objects: \`create_document(sceneId, "Red Cube")\`
-3. Set 3D properties: \`update_metadata(objId, { spShape: "box", spColor: "#ef4444", spX: 0, spY: 1, spZ: 0, spSX: 2, spSY: 2, spSZ: 2 })\`
-4. Shapes: \`"box"\`, \`"sphere"\`, \`"cylinder"\`, \`"cone"\`, \`"plane"\`, \`"torus"\`, \`"glb"\` (uploaded 3D model)
+3. Set 3D properties: \`update_metadata(objId, { spShape: "box", color: "#ef4444", spX: 0, spY: 1, spZ: 0, spSX: 2, spSY: 2, spSZ: 2 })\`
+4. Shapes: \`"box"\`, \`"sphere"\`, \`"cylinder"\`, \`"cone"\`, \`"plane"\`, \`"torus"\`, \`"glb"\` (uploaded 3D model — set \`spModelUploadId\` and \`spModelDocId\`)
 5. Rotation (degrees): \`spRX\`, \`spRY\`, \`spRZ\`. Scale: \`spSX\`, \`spSY\`, \`spSZ\` (default 1). Opacity: \`spOpacity\` (0–100)
+6. Use the universal \`color\` key — **never \`spColor\`**
 
 **Outline (nested items):**
 1. \`create_document(parentId, "Meeting Notes", "outline")\`
 2. Create items: \`create_document(outlineId, "Agenda Item 1")\`
 3. Create sub-items (unlimited depth): \`create_document(itemId, "Sub-point")\`
 
+**Slides (presentation with two-axis nav):**
+1. \`create_document(parentId, "Q1 Review", "slides")\`
+2. Create slides as direct children: \`create_document(deckId, "Intro")\`
+3. Create sub-slides (vertical navigation) as grandchildren: \`create_document(slideId, "Deep dive")\`
+4. Per-slide transition: \`update_metadata(slideId, { slidesTransition: "fade", color: "#6366f1" })\`
+5. Deck-level theme: \`update_metadata(deckId, { slidesTheme: "dark" })\`
+
+**Chart (data viz — manual or aggregation):**
+1. \`create_document(parentId, "Sales", "chart")\`
+2. Configure: \`update_metadata(chartId, { chartType: "bar", chartMetric: "value", chartShowLegend: true, chartLimit: 10 })\`
+3. Modes:
+   - **Manual data points**: create children with \`number\` (value) and optional \`tags\`/\`color\`
+     \`create_document(chartId, "Q1")\` then \`update_metadata(dpId, { number: 42500, color: "#6366f1" })\`
+   - **Aggregation**: set \`chartMetric\` to \`"type"\`/\`"tag"\`/\`"status"\`/\`"priority"\`/\`"activity"\`/\`"completion"\` and point the chart at a subtree — it aggregates the descendants' meta automatically
+4. Chart types: \`"bar"\`, \`"stacked bar"\`, \`"line"\`, \`"donut"\`, \`"treemap"\`
+5. Color schemes: \`"default"\`, \`"warm"\`, \`"cool"\`, \`"mono"\`
+
+**Sheets (spreadsheet with formulas):**
+1. \`create_document(parentId, "Budget", "sheets")\`
+2. Create columns: \`create_document(sheetId, "A")\`, \`create_document(sheetId, "B")\`
+3. Create cells under columns (positional rows, like \`table\`)
+4. Formulas on cells: \`update_metadata(cellId, { formula: "=A1+B1" })\`
+5. Cell formatting: \`update_metadata(cellId, { bold: true, bgColor: "#fef3c7", align: "right" })\`
+6. Deck config: \`update_metadata(sheetId, { sheetsDefaultColWidth: 120, sheetsDefaultRowHeight: 28, sheetsShowGridlines: true, sheetsFreezeRows: 1, sheetsFreezeCols: 1 })\`
+
+**Overview (space home):**
+1. \`create_document(parentId, "Home", "overview")\`
+2. No children required — renders activity, people, stats from the surrounding space
+3. Children (if any) show as linked pages
+
+**Call (video room):**
+1. \`create_document(parentId, "Daily Standup", "call")\`
+2. Video rooms have **no children** — do not add documents underneath
+
+**Coder (multi-file collaborative editor)** *(requires coder plugin):*
+1. \`create_document(parentId, "My App", "coder")\`
+2. Create files/folders: \`create_document(projectId, "App.vue")\`, \`create_document(projectId, "src")\`
+3. Set file type: \`update_metadata(fileId, { fileType: "vue", entry: true })\`
+4. \`fileType\` options: \`"vue"\`, \`"ts"\`, \`"js"\`, \`"css"\`, \`"json"\`, \`"folder"\`
+5. Mark the entry file with \`entry: true\` — the renderer uses it as the preview root
+
+**Media (audio/video playlist)** *(requires media plugin):*
+1. \`create_document(parentId, "Focus Mix", "media")\`
+2. Create tracks: \`create_document(playlistId, "Track 1")\` — attach audio/video file via upload tool
+3. Playlist config: \`update_metadata(playlistId, { mediaRepeat: "all", mediaShuffle: false })\`
+
 ---
 
 ## Document References
@@ -22880,22 +23770,55 @@ In the **graph** page type, document references (embeds and links) create visibl
 |-----|------|-----------|--------|
 | \`kanbanColumnWidth\` | string | kanban | "narrow", "default", "wide" |
 | \`galleryColumns\` | number | gallery | 1–6 |
-| \`galleryAspect\` | string | gallery | "square", "4:3", "16:9" |
+| \`galleryAspect\` | string | gallery | "square", "4:3", "3:2", "16:9", "free" |
+| \`galleryCardStyle\` | string | gallery | "default", "compact", "detailed" |
+| \`galleryShowLabels\` | boolean | gallery | show item labels |
+| \`gallerySortBy\` | string | gallery | "manual", "date", "name", "rating" |
 | \`calendarView\` | string | calendar | "month", "week", "day" |
 | \`calendarWeekStart\` | string | calendar | "sun", "mon" |
+| \`calendarShowWeekNumbers\` | boolean | calendar | — |
 | \`tableMode\` | string | table | "hierarchy", "flat" |
+| \`tableSortKey\` | string | table | meta key to sort by |
+| \`tableSortDir\` | string | table | "asc", "desc" |
+| \`timelineZoom\` | string | timeline | "week", "month", "quarter" |
+| \`timelinePixelsPerDay\` | number | timeline | zoom granularity |
+| \`timelineCenterDate\` | string | timeline | ISO date to center view |
+| \`checklistFilter\` | string | checklist | "all", "active", "completed" |
+| \`checklistSort\` | string | checklist | "manual", "priority", "due" |
+| \`mapShowLabels\` | boolean | map | — |
+| \`graphSpacing\` | string | graph | "compact", "default", "spacious" |
+| \`graphShowLabels\` | boolean | graph | — |
+| \`graphEdgeThickness\` | string | graph | "thin", "normal", "thick" |
 | \`showRefEdges\` | boolean | graph | show doc-reference edges |
-
-### Spatial 3D Keys (for spatial children)
+| \`mmSpacing\` | string | mindmap-layout | spacing between branches |
+| \`spatialGridVisible\` | boolean | spatial | show ground grid |
+| \`slidesTheme\` | string | slides | "dark", "light" |
+| \`chartType\` | string | chart | "bar", "stacked bar", "line", "donut", "treemap" |
+| \`chartMetric\` | string | chart | "value", "type", "tag", "status", "priority", "activity", "completion" |
+| \`chartColorScheme\` | string | chart | "default", "warm", "cool", "mono" |
+| \`chartLimit\` | number | chart | 3–30 (max items) |
+| \`chartShowLegend\` | boolean | chart | — |
+| \`chartShowValues\` | boolean | chart | — |
+| \`sheetsDefaultColWidth\` | number | sheets | 40–500 |
+| \`sheetsDefaultRowHeight\` | number | sheets | 20–100 |
+| \`sheetsShowGridlines\` | boolean | sheets | — |
+| \`sheetsFreezeRows\` | number | sheets | frozen rows count |
+| \`sheetsFreezeCols\` | number | sheets | frozen cols count |
+| \`mediaRepeat\` | string | media | "off", "all", "one" (plugin) |
+| \`mediaShuffle\` | boolean | media | plugin |
+
+### Spatial 3D Keys (for spatial children — requires spatial plugin)
 
 | Key | Type | Default | Meaning |
 |-----|------|---------|---------|
 | \`spShape\` | string | — | "box", "sphere", "cylinder", "cone", "plane", "torus", "glb" |
-| \`spColor\` | string | — | CSS color |
+| \`color\` | string | — | CSS color — universal key, **not** \`spColor\` |
 | \`spOpacity\` | number | 100 | 0–100 |
 | \`spX\`, \`spY\`, \`spZ\` | number | 0 | Position |
 | \`spRX\`, \`spRY\`, \`spRZ\` | number | 0 | Rotation (degrees) |
 | \`spSX\`, \`spSY\`, \`spSZ\` | number | 1 | Scale |
+| \`spModelUploadId\` | string | — | GLB upload ID (when \`spShape: "glb"\`) |
+| \`spModelDocId\` | string | — | Doc ID that owns the GLB upload |
 
 ### Dashboard Keys (for dashboard children)
 
@@ -22905,6 +23828,28 @@ In the **graph** page type, document references (embeds and links) create visibl
 | \`deskZ\` | number | Z-index (layering) |
 | \`deskMode\` | string | "icon", "widget-sm" (240×180), "widget-lg" (400×320) |
 
+### Sheets Cell Formatting (per-cell meta)
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| \`formula\` | string | Cell formula (e.g. "=A1+B1") |
+| \`bold\` | boolean | — |
+| \`italic\` | boolean | — |
+| \`textColor\` | string | CSS color |
+| \`bgColor\` | string | CSS color |
+| \`align\` | string | "left", "center", "right" |
+
+### Coder Keys (for coder children — plugin)
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| \`fileType\` | string | "vue", "ts", "js", "css", "json", "folder" |
+| \`entry\` | boolean | Mark this file as the preview entry point |
+
+### Discovering What Metadata Applies
+
+Use the \`list_page_types\` tool to enumerate all known page types and their declared \`metaSchema\` (fields that apply to children/descendants) and \`defaultMetaFields\` (renderer config fields on the page itself). It's the authoritative list of what meta keys make sense for any given page type.
+
 ---
 
 ## Content Structure
@@ -22987,8 +23932,11 @@ Always clear fields when done by setting them to \`null\`.
 | **Outline** | \`outline:editing\` | nodeId | Editing an outline node |
 | **Gallery** | \`gallery:focused\` | itemId | Item hovered/selected |
 | **Timeline** | \`timeline:focused\` | taskId | Task selected |
-| **Mindmap** | \`mindmap:focused\` | nodeId | Node selected/edited |
 | **Graph** | \`graph:focused\` | nodeId | Node hovered/selected |
+| **Slides** | \`slides:current\` | slideId | Slide being presented |
+| **Spatial** | \`spatial:selected\`, \`spatial:camera\` | objectId / camera state | plugin |
+| **Media** | \`media:playing\`, \`media:position\` | trackId / 0–1 | plugin |
+| **Coder** | \`coder:activeFile\` | fileId | plugin |
 | **Map** | \`map:focused\` | markerId | Marker hovered/selected |
 | **Doc** | \`doc:scroll\` | 0–1 number | Scroll position in document |
 
@@ -23331,6 +24279,9 @@ var HookBridge = class {
 	}
 	routeEvent(payload) {
 		switch (payload.hook_event_name) {
+			case "UserPromptSubmit":
+				this.onUserPromptSubmit();
+				break;
 			case "PreToolUse":
 				this.onPreToolUse(payload);
 				break;
@@ -23341,13 +24292,18 @@ var HookBridge = class {
 				this.onSubagentStart(payload);
 				break;
 			case "SubagentStop":
-				this.onSubagentStop(payload);
+				this.onSubagentStop();
 				break;
 			case "Stop":
 				this.onStop();
 				break;
 		}
 	}
+	/** New user turn — reset any lingering status/tool state from the previous turn. */
+	onUserPromptSubmit() {
+		this.server.setAutoStatus(null);
+		this.server.setActiveToolCall(null);
+	}
 	onPreToolUse(payload) {
 		const toolName = payload.tool_name ?? "";
 		if (toolName.startsWith("mcp__abracadabra__")) return;
@@ -23359,7 +24315,6 @@ var HookBridge = class {
 	}
 	onPostToolUse(payload) {
 		if ((payload.tool_name ?? "").startsWith("mcp__abracadabra__")) return;
-		this.server.setAutoStatus("thinking");
 	}
 	onSubagentStart(payload) {
 		const agentType = payload.agent_type ?? "agent";
@@ -23369,9 +24324,7 @@ var HookBridge = class {
 		});
 		this.server.setAutoStatus("thinking");
 	}
-	onSubagentStop(_payload) {
-		this.server.setAutoStatus("thinking");
-	}
+	onSubagentStop() {}
 	onStop() {
 		this.server.setAutoStatus(null);
 		this.server.setActiveToolCall(null);
@@ -23384,11 +24337,19 @@ var HookBridge = class {
 * Abracadabra MCP Server — entry point.
 *
 * Environment variables:
-*   ABRA_URL         (required) — Server URL (e.g. http://localhost:1234)
+*   ABRA_URL                    (required) — Server URL (e.g. http://localhost:1234)
 *   ABRA_AGENT_NAME             — Display name (default: "AI Assistant")
 *   ABRA_AGENT_COLOR            — HSL color for presence (default: "hsl(270, 80%, 60%)")
 *   ABRA_INVITE_CODE            — Invite code for first-run registration (grants role)
 *   ABRA_KEY_FILE               — Path to Ed25519 key file (default: ~/.abracadabra/agent.key)
+*   ABRA_AGENT_TRIGGER_MODE     — When to respond in group chats:
+*                                   all          → every message (legacy)
+*                                   mention      → only when @<alias> is used
+*                                   task         → only ai:task awareness events
+*                                   mention+task → mention OR ai:task (default)
+*                                 DMs always trigger regardless of mode.
+*   ABRA_AGENT_MENTION_ALIASES  — Comma-separated aliases for @mentions
+*                                 (default: [ABRA_AGENT_NAME])
 */
 async function main() {
 	const url = process.env.ABRA_URL;
@@ -23396,13 +24357,27 @@ async function main() {
 		console.error("Missing required environment variable: ABRA_URL");
 		process.exit(1);
 	}
+	const rawMode = (process.env.ABRA_AGENT_TRIGGER_MODE ?? "mention+task").trim().toLowerCase();
+	const validModes = [
+		"all",
+		"mention",
+		"task",
+		"mention+task"
+	];
+	const triggerMode = validModes.includes(rawMode) ? rawMode : "mention+task";
+	if (rawMode && !validModes.includes(rawMode)) console.error(`[abracadabra-mcp] Invalid ABRA_AGENT_TRIGGER_MODE="${rawMode}", falling back to "mention+task"`);
+	const aliasEnv = process.env.ABRA_AGENT_MENTION_ALIASES;
+	const mentionAliases = aliasEnv ? aliasEnv.split(",").map((a) => a.trim()).filter((a) => a.length > 0) : void 0;
 	const server = new AbracadabraMCPServer({
 		url,
 		agentName: process.env.ABRA_AGENT_NAME,
 		agentColor: process.env.ABRA_AGENT_COLOR,
 		inviteCode: process.env.ABRA_INVITE_CODE,
-		keyFile: process.env.ABRA_KEY_FILE
+		keyFile: process.env.ABRA_KEY_FILE,
+		triggerMode,
+		mentionAliases
 	});
+	console.error(`[abracadabra-mcp] Trigger mode: ${triggerMode}; aliases: ${server.mentionAliases.join(", ")}`);
 	const mcp = new McpServer({
 		name: "abracadabra",
 		version: "1.0.0"