@abraca/mcp 1.0.15 → 1.0.19

package/dist/abracadabra-mcp.esm.js

@@ -6,9 +6,11 @@ import { AbracadabraClient, AbracadabraProvider, awarenessStatesToArray } from "
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import * as fs from "node:fs";
 import { existsSync } from "node:fs";
+import * as os from "node:os";
 import { homedir } from "node:os";
 import * as path from "node:path";
 import { dirname, join } from "node:path";
+import * as http from "node:http";
 
 //#region \0rolldown/runtime.js
 var __create = Object.create;
@@ -4061,7 +4063,7 @@ const cidrv4 = /^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-
 const cidrv6 = /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|::|([0-9a-fA-F]{1,4})?::([0-9a-fA-F]{1,4}:?){0,6})\/(12[0-8]|1[01][0-9]|[1-9]?[0-9])$/;
 const base64 = /^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$/;
 const base64url = /^[A-Za-z0-9_-]*$/;
-const hostname = /^([a-zA-Z0-9-]+\.)*[a-zA-Z0-9-]+$/;
+const hostname$1 = /^([a-zA-Z0-9-]+\.)*[a-zA-Z0-9-]+$/;
 const e164 = /^\+(?:[0-9]){6,14}[0-9]$/;
 const dateSource = `(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))`;
 const date$1 = /* @__PURE__ */ new RegExp(`^${dateSource}$`);
@@ -4608,7 +4610,7 @@ const $ZodURL = /* @__PURE__ */ $constructor("$ZodURL", (inst, def) => {
 					code: "invalid_format",
 					format: "url",
 					note: "Invalid hostname",
-					pattern: hostname.source,
+					pattern: hostname$1.source,
 					input: payload.value,
 					inst,
 					continue: !def.abort
@@ -19543,6 +19545,9 @@ var AbracadabraMCPServer = class {
 			publicKey: this._userId,
 			isAgent: true
 		});
+		provider.awareness.setLocalStateField("status", null);
+		provider.awareness.setLocalStateField("activeToolCall", null);
+		provider.awareness.setLocalStateField("statusContext", null);
 		const conn = {
 			doc,
 			provider,
@@ -19758,8 +19763,10 @@ var AbracadabraMCPServer = class {
 	}
 	/**
 	* Set the agent's status in root awareness with auto-clear after idle.
+	* @param statusContext — scopes the status to a specific channel/context so the
+	*   dashboard only shows it in the relevant chat. Defaults to `_lastChatChannel`.
 	*/
-	setAutoStatus(status, docId) {
+	setAutoStatus(status, docId, statusContext) {
 		const provider = this._activeConnection?.provider;
 		if (!provider) return;
 		if (this._statusClearTimer) {
@@ -19768,12 +19775,15 @@ var AbracadabraMCPServer = class {
 		}
 		provider.awareness.setLocalStateField("status", status);
 		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._statusClearTimer = setTimeout(() => {
 			provider.awareness.setLocalStateField("status", null);
 			provider.awareness.setLocalStateField("activeToolCall", null);
+			provider.awareness.setLocalStateField("statusContext", null);
 			this._stopTypingInterval();
-		}, 3e4);
+		}, 1e4);
 	}
 	/** Re-send typing indicator every 2s so dashboard keeps showing it (expires at 3s). */
 	_startTypingInterval(channel) {
@@ -19821,7 +19831,12 @@ var AbracadabraMCPServer = class {
 		}
 		for (const [, cached] of this.childCache) cached.provider.destroy();
 		this.childCache.clear();
-		for (const [, conn] of this._spaceConnections) conn.provider.destroy();
+		for (const [, conn] of this._spaceConnections) {
+			conn.provider.awareness.setLocalStateField("status", null);
+			conn.provider.awareness.setLocalStateField("activeToolCall", null);
+			conn.provider.awareness.setLocalStateField("statusContext", null);
+			conn.provider.destroy();
+		}
 		this._spaceConnections.clear();
 		this._activeConnection = null;
 		console.error("[abracadabra-mcp] Shutdown complete");
@@ -19963,7 +19978,7 @@ 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: \"doc\", \"kanban\", \"calendar\", \"table\", \"outline\", \"gallery\", \"slides\", \"timeline\", \"whiteboard\", \"map\", \"dashboard\", \"mindmap\", \"graph\". Omit to inherit parent view."),
+		type: z.string().optional().describe("Page type — sets how this document renders. \"doc\" (rich text), \"kanban\" (columns → cards), \"table\" (columns → cells, positional rows), \"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\" (image/media items), \"map\" (markers/lines with geoLat/geoLng), \"graph\" (knowledge graph nodes), \"dashboard\" (positioned widgets with deskX/deskY/deskMode), \"mindmap\" (connected nodes), \"spatial\" (3D objects with spShape/spX/spY/spZ), \"media\" (audio/video tracks), \"slides\" (slide deck), \"whiteboard\" (freeform canvas). 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.")
 	}, async ({ parentId, label, type, meta }) => {
 		server.setAutoStatus("creating");
@@ -19994,6 +20009,7 @@ function registerTreeTools(mcp, server) {
 				updatedAt: now
 			});
 		});
+		server.setFocusedDoc(id);
 		server.setActiveToolCall(null);
 		return { content: [{
 			type: "text",
@@ -20149,6 +20165,7 @@ function registerTreeTools(mcp, server) {
 			label: (entry.label || "Untitled") + " (copy)",
 			order: Date.now()
 		});
+		server.setFocusedDoc(newId);
 		return { content: [{
 			type: "text",
 			text: JSON.stringify({
@@ -20234,11 +20251,44 @@ function parseFrontmatter(markdown) {
 	if (subtitle) meta.subtitle = subtitle;
 	const url = getStr(["url"]);
 	if (url) meta.url = url;
+	const email = getStr(["email"]);
+	if (email) meta.email = email;
+	const phone = getStr(["phone"]);
+	if (phone) meta.phone = phone;
 	const ratingRaw = getStr(["rating"]);
 	if (ratingRaw !== void 0) {
 		const n = Number(ratingRaw);
 		if (!Number.isNaN(n)) meta.rating = Math.min(5, Math.max(0, n));
 	}
+	const datetimeStart = getStr(["datetimeStart"]);
+	if (datetimeStart) meta.datetimeStart = datetimeStart;
+	const datetimeEnd = getStr(["datetimeEnd"]);
+	if (datetimeEnd) meta.datetimeEnd = datetimeEnd;
+	const allDayRaw = raw["allDay"];
+	if (allDayRaw !== void 0) meta.allDay = allDayRaw === "true" || allDayRaw === true;
+	const geoLatRaw = getStr(["geoLat"]);
+	if (geoLatRaw !== void 0) {
+		const n = Number(geoLatRaw);
+		if (!Number.isNaN(n)) meta.geoLat = n;
+	}
+	const geoLngRaw = getStr(["geoLng"]);
+	if (geoLngRaw !== void 0) {
+		const n = Number(geoLngRaw);
+		if (!Number.isNaN(n)) meta.geoLng = n;
+	}
+	const geoType = getStr(["geoType"]);
+	if (geoType && (geoType === "marker" || geoType === "line" || geoType === "measure")) meta.geoType = geoType;
+	const geoDescription = getStr(["geoDescription"]);
+	if (geoDescription) meta.geoDescription = geoDescription;
+	const numberRaw = getStr(["number"]);
+	if (numberRaw !== void 0) {
+		const n = Number(numberRaw);
+		if (!Number.isNaN(n)) meta.number = n;
+	}
+	const unit = getStr(["unit"]);
+	if (unit) meta.unit = unit;
+	const note = getStr(["note"]);
+	if (note) meta.note = note;
 	return {
 		title: typeof raw["title"] === "string" ? raw["title"] : void 0,
 		meta,
@@ -20276,8 +20326,12 @@ function parseInline(text) {
 				attrs: { kbd: { value: kbdProps["value"] || "" } }
 			});
 		} else if (match[5] !== void 0) {
-			const displayText = match[6] ?? match[5];
-			tokens.push({ text: displayText });
+			const docId = match[5];
+			const displayText = match[6] ?? docId;
+			tokens.push({
+				text: displayText,
+				attrs: { link: { href: `/doc/${docId}` } }
+			});
 		} else if (match[7] !== void 0) tokens.push({
 			text: match[7],
 			attrs: { strike: true }
@@ -20426,6 +20480,15 @@ function parseBlocks(markdown) {
 			i++;
 			continue;
 		}
+		const docEmbedMatch = line.match(/^!\[\[([^\]|]+?)(?:\|[^\]]*?)?\]\]\s*$/);
+		if (docEmbedMatch) {
+			blocks.push({
+				type: "docEmbed",
+				docId: docEmbedMatch[1]
+			});
+			i++;
+			continue;
+		}
 		const imgMatch = line.match(/^!\[([^\]]*)\]\(([^)]+)\)(\{[^}]*\})?\s*$/);
 		if (imgMatch) {
 			const alt = imgMatch[1] ?? "";
@@ -20733,6 +20796,7 @@ function blockElName(b) {
 		case "field": return "field";
 		case "fieldGroup": return "fieldGroup";
 		case "image": return "image";
+		case "docEmbed": return "docEmbed";
 	}
 }
 function fillBlock(el, block) {
@@ -20948,6 +21012,9 @@ function fillBlock(el, block) {
 			if (block.width) el.setAttribute("width", block.width);
 			if (block.height) el.setAttribute("height", block.height);
 			break;
+		case "docEmbed":
+			el.setAttribute("docId", block.docId);
+			break;
 	}
 }
 function populateYDocFromMarkdown(fragment, markdown, fallbackTitle = "Untitled") {
@@ -20996,6 +21063,7 @@ function populateYDocFromMarkdown(fragment, markdown, fallbackTitle = "Untitled"
 				case "field": return new Y.XmlElement("field");
 				case "fieldGroup": return new Y.XmlElement("fieldGroup");
 				case "image": return new Y.XmlElement("image");
+				case "docEmbed": return new Y.XmlElement("docEmbed");
 			}
 		});
 		fragment.insert(0, [
@@ -21067,6 +21135,10 @@ function serializeElement(el, indent = "") {
 		}
 		case "horizontalRule": return "---";
 		case "table": return serializeTable(el);
+		case "docEmbed": {
+			const docId = el.getAttribute("docId");
+			return docId ? `![[${docId}]]` : "";
+		}
 		case "image": {
 			const src = el.getAttribute("src") || "";
 			const alt = el.getAttribute("alt") || "";
@@ -21282,7 +21354,7 @@ function registerContentTools(mcp, server) {
 			};
 		}
 	});
-	mcp.tool("write_document", "Write markdown content to a document. Parses the markdown and writes it to the Y.js CRDT document, which syncs in real-time to all connected clients. Supports optional YAML frontmatter for title and metadata.", {
+	mcp.tool("write_document", "Write markdown content to a document. Parses the markdown and writes it to the Y.js CRDT document, which syncs in real-time to all connected clients. Supports optional YAML frontmatter for title and metadata. Use ![[docId]] to embed another document as a block, or [[docId|label]] for inline doc links.", {
 		docId: z.string().describe("Document ID to write to."),
 		markdown: z.string().describe("Markdown content to write. Can include YAML frontmatter with title and metadata fields."),
 		mode: z.enum(["replace", "append"]).optional().describe("Write mode. \"replace\" clears existing content first (default). \"append\" adds to the end.")
@@ -21366,7 +21438,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). Standard PageMeta keys: color (hex string), icon (Lucide kebab-case name like \"star\"/\"code-2\"/\"users\" — NEVER emoji), dateStart, dateEnd, datetimeStart, datetimeEnd, allDay, tags, checked, priority (0-4), status, rating, url, taskProgress (0-100), subtitle, note. Set a key to null to clear it.")
+		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\"). Renderer config (on the page doc itself): kanbanColumnWidth, galleryColumns, galleryAspect, calendarView, calendarWeekStart, tableMode, showRefEdges. Set a key to null to clear it.")
 	}, async ({ docId, meta }) => {
 		const treeMap = server.getTreeMap();
 		if (!treeMap) return { content: [{
@@ -21714,6 +21786,18 @@ Every piece of visible data in Abracadabra — a calendar event, a kanban card,
 
 **Page types are views over the same document hierarchy**, not isolated data stores. Switching a page from Kanban to Table to Outline works without migration — the tree doesn't change, only the rendering.
 
+The same tree viewed as different page types:
+\`\`\`
+My Doc
+├── "To Do"       → Kanban: column / Table: column / Outline: item
+│   ├── "Fix bug" → Kanban: card   / Table: cell   / Outline: sub-item
+│   └── "Add tests"
+├── "In Progress"
+│   └── "Refactor"
+└── "Done"
+    └── "Deploy"
+\`\`\`
+
 ---
 
 ## Getting Oriented in a Space
@@ -21733,23 +21817,24 @@ If you are adding content to an existing space, call \`get_document_tree(rootId:
 
 ## Page Types Reference
 
-| Type | Children Are | Grandchildren Are | Depth Limit |
-|------|-------------|-------------------|-------------|
-| **doc** | Sub-documents | Sub-sub-documents | Unlimited |
-| **kanban** | Columns | Cards | 2 |
-| **table** | Columns | Cells (positional rows) | 2 |
-| **calendar** | Events | — | 1 |
-| **timeline** | Epics | Tasks | 2 |
-| **outline** | Items | Sub-items | Unlimited |
-| **mindmap** | Central nodes | Branches | Unlimited |
-| **graph** | Nodes | — | 1 |
-| **gallery** | Items | — | 1 |
-| **slides** | Slides | — | 1 |
-| **whiteboard** | Objects | — | 1 |
-| **map** | Markers/Lines | Points (for lines) | 2 |
-| **desktop** | Items | — | 1 |
-| **call** | — | — | 0 |
-| **game** | — | — | 0 |
+| 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 |
+| **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 |
+| **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 |
 
 ---
 
@@ -21758,26 +21843,110 @@ If you are adding content to an existing space, call \`get_document_tree(rootId:
 ### Creating Well-Structured Hierarchies
 
 **Kanban board:**
-1. Create the kanban document: \`create_document(parentId, "Project Board", "kanban")\`
+1. \`create_document(parentId, "Project Board", "kanban")\`
 2. Create columns: \`create_document(boardId, "To Do")\`, \`create_document(boardId, "In Progress")\`, \`create_document(boardId, "Done")\`
 3. Create cards under columns: \`create_document(toDoColumnId, "Fix bug #123")\`
+4. Optionally set card metadata: \`update_metadata(cardId, { color: "#ef4444", priority: 3, tags: ["urgent"] })\`
+5. Optionally configure column width: \`update_metadata(boardId, { kanbanColumnWidth: "wide" })\`
+
+**Table with data:**
+1. \`create_document(parentId, "Contacts", "table")\`
+2. Create columns: \`create_document(tableId, "Name")\`, \`create_document(tableId, "Email")\`, \`create_document(tableId, "Phone")\`
+3. Create cells (children of columns): \`create_document(nameColId, "Alice")\`, \`create_document(emailColId, "alice@example.com")\`
+4. **Rows are positional** — the Nth child of each column forms row N
+5. Row count = max children across all columns. Missing cells render as empty.
+6. To add a row: create a child under each column at the same index position
+7. To delete row N: delete the Nth child from every column
 
 **Calendar with events:**
-1. Create calendar: \`create_document(parentId, "Team Calendar", "calendar")\`
+1. \`create_document(parentId, "Team Calendar", "calendar")\`
 2. Create events: \`create_document(calendarId, "Sprint Planning")\`
 3. Set event times: \`update_metadata(eventId, { datetimeStart: "2026-03-20T10:00:00Z", datetimeEnd: "2026-03-20T11:00:00Z" })\`
+4. All-day events: \`update_metadata(eventId, { datetimeStart: "2026-03-20", allDay: true })\`
+5. Multi-day events: \`update_metadata(eventId, { datetimeStart: "2026-03-20", datetimeEnd: "2026-03-22", allDay: true })\`
+6. Configure view: \`update_metadata(calendarId, { calendarView: "week" })\`
 
-**Timeline with tasks:**
-1. Create timeline: \`create_document(parentId, "Q1 Roadmap", "timeline")\`
+**Timeline (Gantt chart):**
+1. \`create_document(parentId, "Q1 Roadmap", "timeline")\`
 2. Create epics: \`create_document(timelineId, "Auth Rewrite")\`
-3. Create tasks: \`create_document(epicId, "Implement JWT refresh")\`
-4. Set dates/progress: \`update_metadata(taskId, { dateStart: "2026-03-01", dateEnd: "2026-03-15", taskProgress: 50 })\`
+3. Create tasks under epics: \`create_document(epicId, "Implement JWT refresh")\`
+4. Set dates and progress: \`update_metadata(taskId, { dateStart: "2026-03-01", dateEnd: "2026-03-15", taskProgress: 50, color: "#6366f1" })\`
 
-**Table with data:**
-1. Create table: \`create_document(parentId, "Contacts", "table")\`
-2. Create columns: \`create_document(tableId, "Name")\`, \`create_document(tableId, "Email")\`, \`create_document(tableId, "Phone")\`
-3. Create cells (children of columns): \`create_document(nameColId, "Alice")\`, \`create_document(emailColId, "alice@example.com")\`
-4. Rows are positional — the Nth child of each column forms row N
+**Checklist (nested task list):**
+1. \`create_document(parentId, "Sprint Tasks", "checklist")\`
+2. Create tasks: \`create_document(checklistId, "Write tests")\`
+3. Set task properties: \`update_metadata(taskId, { checked: false, priority: 3, dateEnd: "2026-04-01" })\`
+4. Create sub-tasks (unlimited nesting): \`create_document(taskId, "Unit tests")\`
+
+**Map with markers and lines:**
+1. \`create_document(parentId, "Travel Map", "map")\`
+2. Create markers: \`create_document(mapId, "Coffee Shop")\`
+3. Set marker position: \`update_metadata(markerId, { geoType: "marker", geoLat: 37.7749, geoLng: -122.4194, icon: "coffee", color: "#f97316" })\`
+4. Create a line/route: \`create_document(mapId, "Walking Route")\`
+5. Set line properties: \`update_metadata(routeId, { geoType: "line", color: "#3b82f6" })\`
+6. Create line points as children: \`create_document(routeId, "Start")\` then \`update_metadata(pointId, { geoLat: 37.7749, geoLng: -122.4194 })\`
+7. Create measuring tool: set \`geoType: "measure"\` instead of "line"
+
+**Gallery:**
+1. \`create_document(parentId, "Photo Album", "gallery")\`
+2. Create items: \`create_document(galleryId, "Sunset at Beach")\`
+3. Set metadata: \`update_metadata(itemId, { geoLat: 37.7749, geoLng: -122.4194, tags: ["travel", "sunset"] })\`
+4. Configure layout: \`update_metadata(galleryId, { galleryColumns: 4, galleryAspect: "16:9" })\`
+
+**Graph (knowledge graph):**
+1. \`create_document(parentId, "Tech Stack", "graph")\`
+2. Create nodes: \`create_document(graphId, "React")\`, \`create_document(graphId, "Vue")\`
+3. Set node properties: \`update_metadata(nodeId, { color: "#6366f1", icon: "file-code" })\`
+4. Edges are created by parent-child relationships AND document references (doc embeds/links in content)
+5. Enable reference edges: \`update_metadata(graphId, { showRefEdges: true })\`
+
+**Dashboard:**
+1. \`create_document(parentId, "Overview", "dashboard")\`
+2. Create items: \`create_document(dashboardId, "Revenue Chart")\`
+3. Position items on grid: \`update_metadata(itemId, { deskX: 0, deskY: 0, deskMode: "widget-lg" })\`
+4. Modes: \`"icon"\` (small), \`"widget-sm"\` (240×180), \`"widget-lg"\` (400×320)
+5. Grid uses 80px cells
+
+**Spatial (3D scene):**
+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)
+5. Rotation (degrees): \`spRX\`, \`spRY\`, \`spRZ\`. Scale: \`spSX\`, \`spSY\`, \`spSZ\` (default 1). Opacity: \`spOpacity\` (0–100)
+
+**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")\`
+
+---
+
+## Document References
+
+You can link and embed documents within rich-text content:
+
+**Block-level doc embed** — renders an embedded document preview:
+\`\`\`
+![[docId]]
+\`\`\`
+
+**Inline link to another document:**
+\`\`\`
+[Link text](/doc/docId)
+\`\`\`
+
+**Inline wikilink** (shorthand — converted to doc link):
+\`\`\`
+[[docId]]
+[[docId|Display Text]]
+\`\`\`
+
+Example — write content with references:
+\`\`\`
+write_document(docId, "# Project Overview\\n\\nSee the detailed spec:\\n\\n![[specDocId]]\\n\\nCheck the [timeline](/doc/timelineDocId) for dates.")
+\`\`\`
+
+In the **graph** page type, document references (embeds and links) create visible edges between nodes when \`showRefEdges\` is enabled.
 
 ---
 
@@ -21788,7 +21957,7 @@ If you are adding content to an existing space, call \`get_document_tree(rootId:
 | Key | Type | Meaning |
 |-----|------|---------|
 | \`color\` | string | Hex/CSS color (e.g. "#6366f1") |
-| \`icon\` | string | Lucide icon name in kebab-case (e.g. "star", "code-2", "users", "calendar-days", "book-open"). **Never emoji.** Omit to use the page type's default icon. |
+| \`icon\` | string | Lucide icon name in kebab-case (e.g. "star", "code-2", "users"). **Never emoji.** Omit for default. |
 | \`datetimeStart\` / \`datetimeEnd\` | string | ISO datetime with time |
 | \`allDay\` | boolean | Whether datetime is all-day |
 | \`dateStart\` / \`dateEnd\` | string | ISO date-only (e.g. "2026-03-20") |
@@ -21806,45 +21975,86 @@ If you are adding content to an existing space, call \`get_document_tree(rootId:
 | \`subtitle\` | string | Secondary text |
 | \`note\` | string | Free-text note |
 | \`taskProgress\` | number | 0–100 progress (timeline tasks) |
+| \`members\` | { id, label }[] | Assigned users |
+| \`coverUploadId\` | string | Cover image (upload ID from upload_file) |
+
+### Geo/Map Keys (for map children)
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| \`geoType\` | string | "marker", "line", or "measure" |
+| \`geoLat\` | number | Latitude |
+| \`geoLng\` | number | Longitude |
+| \`geoDescription\` | string | Location description text |
+
+### Renderer Config Keys (set on the page doc itself, not its children)
 
-### Type-Specific Meta Schemas
+| Key | Type | Applies to | Values |
+|-----|------|-----------|--------|
+| \`kanbanColumnWidth\` | string | kanban | "narrow", "default", "wide" |
+| \`galleryColumns\` | number | gallery | 1–6 |
+| \`galleryAspect\` | string | gallery | "square", "4:3", "16:9" |
+| \`calendarView\` | string | calendar | "month", "week", "day" |
+| \`calendarWeekStart\` | string | calendar | "sun", "mon" |
+| \`tableMode\` | string | table | "hierarchy", "flat" |
+| \`showRefEdges\` | boolean | graph | show doc-reference edges |
 
-**Calendar events** require: \`datetimeStart\`, \`datetimeEnd\`, optionally \`allDay\`, \`color\`
+### Spatial 3D Keys (for spatial children)
 
-**Timeline tasks** require: \`dateStart\`, \`dateEnd\`, optionally \`taskProgress\` (0–100), \`color\`
+| Key | Type | Default | Meaning |
+|-----|------|---------|---------|
+| \`spShape\` | string | — | "box", "sphere", "cylinder", "cone", "plane", "torus", "glb" |
+| \`spColor\` | string | — | CSS color |
+| \`spOpacity\` | number | 100 | 0–100 |
+| \`spX\`, \`spY\`, \`spZ\` | number | 0 | Position |
+| \`spRX\`, \`spRY\`, \`spRZ\` | number | 0 | Rotation (degrees) |
+| \`spSX\`, \`spSY\`, \`spSZ\` | number | 1 | Scale |
 
-**Map markers** require: \`geoLat\`, \`geoLng\`, \`geoType\` ("marker"|"line"|"measure"), optionally \`icon\`, \`color\`
+### Dashboard Keys (for dashboard children)
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| \`deskX\`, \`deskY\` | number | Grid position (80px cells) |
+| \`deskZ\` | number | Z-index (layering) |
+| \`deskMode\` | string | "icon", "widget-sm" (240×180), "widget-lg" (400×320) |
 
 ---
 
 ## Content Structure
 
-Documents use a TipTap editor schema with these top-level elements:
-- **documentHeader** — The document title (H1)
-- **documentMeta** — Metadata display block (skip when reading/writing)
-- **Body blocks** — paragraphs, headings (H2-H6), lists, code blocks, tables, images, and custom components
-
-### Supported Markdown Elements
+Documents use a TipTap editor schema. The body supports:
 - Headings (# through ######)
-- Paragraphs with **bold**, *italic*, ~~strikethrough~~, \`code\`, [links](url)
-- Bullet lists, ordered lists, task lists
+- Paragraphs with **bold**, *italic*, ~~strikethrough~~, \\\`code\\\`, [links](url)
+- Bullet lists, ordered lists, task lists (- [x] / - [ ])
 - Code blocks with language
 - Blockquotes
 - Tables (pipe syntax)
 - Horizontal rules
-- Images
-- MDC components: callout, collapsible, steps, card, accordion, tabs, code-group, etc.
+- Images: \`![alt](src){width="..." height="..."}\`
+- Document embeds: \`![[docId]]\`
+- Inline doc links: \`[[docId|label]]\` or \`[label](/doc/docId)\`
+- MDC components: \`::tip\`, \`::note\`, \`::warning\`, \`::collapsible\`, \`::steps\`, \`::card\`, \`::accordion\`, \`::tabs\`, \`::code-group\`, etc.
+- Badges: \`:badge[Label]{color="..."}\`
+- Icons: \`:icon{name="star"}\`
 
 ### Writing Content with Frontmatter
 
-You can set document title and metadata via YAML frontmatter:
+Set document title and metadata via YAML frontmatter:
 
 \`\`\`markdown
 ---
 title: My Document
 tags: [important, review]
 color: "#6366f1"
+icon: star
 priority: high
+checked: false
+datetimeStart: "2026-03-20T10:00:00Z"
+datetimeEnd: "2026-03-20T11:00:00Z"
+allDay: false
+geoLat: 37.7749
+geoLng: -122.4194
+geoType: marker
 ---
 
 Content goes here...
@@ -21866,8 +22076,7 @@ You do **not** need to call \`set_presence\` after reading or writing content
 |---|---|
 | \`read_document\` | Root \`docId\` updated; TipTap cursor placed at start of document |
 | \`write_document\` | Root \`docId\` updated; TipTap cursor placed at end of written content |
-
-The TipTap cursor (\`anchor\`/\`head\` as \`Y.RelativePosition\`) makes your colored caret with name label appear inline in the document editor for human collaborators.
+| \`create_document\` | Root \`docId\` updated to the new document |
 
 ### set_presence — manual overrides only
 
@@ -21889,8 +22098,6 @@ Always clear fields when done by setting them to \`null\`.
 | **Calendar** | \`calendar:focused\` | eventId | Interacting with an event |
 | **Calendar** | \`calendar:viewing\` | "YYYY-MM" | The month/week you're looking at |
 | **Outline** | \`outline:editing\` | nodeId | Editing an outline node |
-| **Outline** | \`outline:selected\` | nodeId | Node selected/hovered |
-| **Slides** | \`slides:viewing\` | slideId | The slide you're currently on |
 | **Gallery** | \`gallery:focused\` | itemId | Item hovered/selected |
 | **Timeline** | \`timeline:focused\` | taskId | Task selected |
 | **Mindmap** | \`mindmap:focused\` | nodeId | Node selected/edited |
@@ -21898,7 +22105,7 @@ Always clear fields when done by setting them to \`null\`.
 | **Map** | \`map:focused\` | markerId | Marker hovered/selected |
 | **Doc** | \`doc:scroll\` | 0–1 number | Scroll position in document |
 
-Example — mark a kanban card as being inspected, then clear on completion:
+Example — mark a kanban card as being inspected, then clear:
 \`\`\`
 set_doc_awareness(boardDocId, { "kanban:hovering": cardId })
 // ... do work ...
@@ -21909,73 +22116,48 @@ set_doc_awareness(boardDocId, { "kanban:hovering": null })
 
 ## Receiving Instructions from Humans
 
-Three ways humans can send you tasks:
-
 **Channel events (preferred):** When running in channel mode, \`ai:task\` events from
 human users arrive as \`<channel source="abracadabra" ...>\` notifications directly in
-your session. These include the sender name, task ID, and document context. Use the
-\`reply\` tool to send your response back — it creates a reply document and signals
-task completion.
+your session. Use the \`reply\` tool to send your response — it creates a reply document
+and signals task completion.
 
-**Chat document watching:** Use \`watch_chat\` to observe a document for new messages.
-Changes are pushed as channel notifications in real time. Reply using the \`reply\` tool
-with the chat document's ID.
+**Chat messages:** Chat messages from the platform arrive as channel notifications. Use
+\`send_chat_message\` to respond in the same channel.
 
 **Polling (fallback):** Call \`poll_inbox\` to read the "AI Inbox" document.
-Act on any pending tasks you find there. Write your response back with \`write_document\`
-or \`create_document\` under the inbox.
-
-### Channel Tools
-
-| Tool | Purpose |
-|------|---------|
-| \`reply\` | Send a reply to Abracadabra — creates a child doc with your response. Pass \`task_id\` to signal ai:task completion. |
-| \`watch_chat\` | Start/stop watching a document for chat messages. New content arrives as channel notifications. |
-
-When you complete a task, always use \`reply\` (in channel mode) or write a response
-document (in polling mode) so the human knows the work is done.
 
 ---
 
 ## Common Patterns
 
-### Populate a kanban board from a list
-\`\`\`
-1. create_document → kanban parent
-2. For each column: create_document under kanban
-3. For each card: create_document under the appropriate column
-4. Optionally set metadata (color, tags, priority) on cards
-\`\`\`
-
 ### Explore a document fully (the correct way)
 \`\`\`
-User: "Check out the Marketing doc"
-
-1. read_document(marketingId)
+1. read_document(docId)
    → returns { markdown, children: [...] }
 2. The body may be empty — that does NOT mean the doc is empty.
    Children ARE the content. Read every child:
    read_document(childId1), read_document(childId2), ...
-3. Each child's response also includes ITS children.
-   Continue recursively until no children remain.
+3. Continue recursively until no children remain.
 \`\`\`
 
 **Never conclude a document is "empty" just because its markdown body is empty.
 Always check and traverse the \`children\` array returned by \`read_document\`.**
 
-### Write rich content to a document
+### Populate a kanban board from a list
 \`\`\`
-1. read_document to see current content (and children)
-2. write_document with markdown (mode: "replace" to overwrite, "append" to add)
-3. Include frontmatter for title/metadata if needed
+1. create_document → kanban parent
+2. For each column: create_document under kanban
+3. For each card: create_document under the appropriate column
+4. Optionally set metadata (color, tags, priority) on cards
 \`\`\`
 
-### Organize documents into a hierarchy
+### Write rich content with references
 \`\`\`
-1. get_document_tree to understand current structure
-2. create_document to add new nodes
-3. move_document to reorganize
-4. change_document_type to switch views
+1. read_document to see current content (and children)
+2. write_document with markdown (mode: "replace" or "append")
+3. Use ![[docId]] to embed other documents
+4. Use [[docId|label]] for inline doc links
+5. Include frontmatter for title/metadata if needed
 \`\`\`
 
 ---
@@ -22001,6 +22183,7 @@ Always check and traverse the \`children\` array returned by \`read_document\`.*
 - Use emoji as \`icon\` values — only lowercase kebab-case Lucide icon names are valid
 - Create top-level documents without first confirming the correct hub doc ID
 - Rename or write content to the space hub document itself
+- Set \`type\` on child items (cards, cells, events) — only set type on the parent page
 `;
 function registerAgentGuide(mcp) {
 	mcp.resource("agent-guide", "abracadabra://agent-guide", {
@@ -22093,6 +22276,221 @@ function registerServerInfoResource(mcp, server) {
 	});
 }
 
+//#endregion
+//#region packages/mcp/src/tools/hooks.ts
+function registerHookTools(mcp, hookBridge) {
+	mcp.tool("get_hook_config", "Returns Claude Code hook configuration JSON for bridging activity to the Abracadabra dashboard. Copy the \"hooks\" object into your .claude/settings.local.json to enable real-time activity indicators (tool calls, subagents, etc.) visible to all connected users.", {}, async () => {
+		const port = hookBridge.port;
+		if (!port) return {
+			content: [{
+				type: "text",
+				text: "Hook bridge is not running."
+			}],
+			isError: true
+		};
+		const hookEntry = {
+			type: "http",
+			url: `http://127.0.0.1:${port}/hook`,
+			timeout: 3
+		};
+		const config = { hooks: {
+			PreToolUse: [{ hooks: [hookEntry] }],
+			PostToolUse: [{ hooks: [hookEntry] }],
+			SubagentStart: [{ hooks: [hookEntry] }],
+			SubagentStop: [{ hooks: [hookEntry] }],
+			Stop: [{ hooks: [hookEntry] }]
+		} };
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(config, null, 2)
+		}] };
+	});
+}
+
+//#endregion
+//#region packages/mcp/src/hook-bridge.ts
+/**
+* HookBridge — lightweight HTTP server that receives Claude Code hook events
+* and translates them into Yjs awareness updates via AbracadabraMCPServer.
+*
+* Claude Code hooks (PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop)
+* POST JSON to http://127.0.0.1:{port}/hook. The bridge maps these to awareness
+* fields (status, activeToolCall) so the cou-sh dashboard shows real-time activity.
+*/
+/** Map Claude Code tool names to awareness-friendly names + extract a target string. */
+function mapToolCall(toolName, toolInput) {
+	switch (toolName) {
+		case "Bash": return {
+			name: "bash",
+			target: truncate(toolInput.command ?? toolInput.description, 60)
+		};
+		case "Read": return {
+			name: "read_file",
+			target: basename(toolInput.file_path)
+		};
+		case "Edit": return {
+			name: "edit_file",
+			target: basename(toolInput.file_path)
+		};
+		case "Write": return {
+			name: "write_file",
+			target: basename(toolInput.file_path)
+		};
+		case "Grep": return {
+			name: "grep",
+			target: truncate(toolInput.pattern, 40)
+		};
+		case "Glob": return {
+			name: "glob",
+			target: truncate(toolInput.pattern, 40)
+		};
+		case "Agent": return {
+			name: "subagent",
+			target: toolInput.description || toolInput.subagent_type || "agent"
+		};
+		case "WebFetch": return {
+			name: "web_fetch",
+			target: hostname(toolInput.url)
+		};
+		case "WebSearch": return {
+			name: "web_search",
+			target: truncate(toolInput.query, 40)
+		};
+		default: return { name: toolName.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase() };
+	}
+}
+function truncate(str, max) {
+	if (!str) return void 0;
+	return str.length > max ? str.slice(0, max) + "..." : str;
+}
+function basename(filePath) {
+	if (!filePath) return void 0;
+	return path.basename(filePath);
+}
+function hostname(url) {
+	if (!url) return void 0;
+	try {
+		return new URL(url).hostname;
+	} catch {
+		return url.slice(0, 30);
+	}
+}
+var HookBridge = class {
+	constructor(server) {
+		this.server = server;
+		this.httpServer = null;
+		this._port = null;
+		this.portFilePath = process.env.ABRA_HOOK_PORT_FILE || path.join(os.tmpdir(), "abracadabra-mcp-hook.port");
+	}
+	get port() {
+		return this._port;
+	}
+	/** Start the HTTP server on a random port and write the port file. */
+	async start() {
+		return new Promise((resolve, reject) => {
+			const srv = http.createServer((req, res) => this.handleRequest(req, res));
+			srv.on("error", reject);
+			srv.listen(0, "127.0.0.1", () => {
+				const addr = srv.address();
+				if (!addr || typeof addr === "string") {
+					reject(/* @__PURE__ */ new Error("Failed to get server address"));
+					return;
+				}
+				this._port = addr.port;
+				this.httpServer = srv;
+				try {
+					fs.writeFileSync(this.portFilePath, String(this._port), "utf-8");
+				} catch (err) {
+					console.error(`[hook-bridge] Warning: could not write port file: ${err.message}`);
+				}
+				console.error(`[hook-bridge] Listening on 127.0.0.1:${this._port}`);
+				console.error(`[hook-bridge] Port file: ${this.portFilePath}`);
+				resolve(this._port);
+			});
+		});
+	}
+	/** Shut down the HTTP server and remove the port file. */
+	async destroy() {
+		if (this.httpServer) {
+			await new Promise((resolve) => {
+				this.httpServer.close(() => resolve());
+			});
+			this.httpServer = null;
+		}
+		try {
+			fs.unlinkSync(this.portFilePath);
+		} catch {}
+		this._port = null;
+		console.error("[hook-bridge] Shut down");
+	}
+	handleRequest(req, res) {
+		if (req.method !== "POST" || req.url !== "/hook") {
+			res.writeHead(404);
+			res.end();
+			return;
+		}
+		let body = "";
+		req.on("data", (chunk) => {
+			body += chunk.toString();
+		});
+		req.on("end", () => {
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end("{}");
+			try {
+				const payload = JSON.parse(body);
+				this.routeEvent(payload);
+			} catch {}
+		});
+	}
+	routeEvent(payload) {
+		switch (payload.hook_event_name) {
+			case "PreToolUse":
+				this.onPreToolUse(payload);
+				break;
+			case "PostToolUse":
+				this.onPostToolUse(payload);
+				break;
+			case "SubagentStart":
+				this.onSubagentStart(payload);
+				break;
+			case "SubagentStop":
+				this.onSubagentStop(payload);
+				break;
+			case "Stop":
+				this.onStop();
+				break;
+		}
+	}
+	onPreToolUse(payload) {
+		const toolName = payload.tool_name ?? "";
+		if (toolName.startsWith("mcp__abracadabra__")) return;
+		const mapped = mapToolCall(toolName, payload.tool_input ?? {});
+		if (mapped) {
+			this.server.setActiveToolCall(mapped);
+			this.server.setAutoStatus("working");
+		}
+	}
+	onPostToolUse(payload) {
+		if ((payload.tool_name ?? "").startsWith("mcp__abracadabra__")) return;
+		this.server.setActiveToolCall(null);
+	}
+	onSubagentStart(payload) {
+		const agentType = payload.agent_type ?? "agent";
+		this.server.setActiveToolCall({
+			name: "subagent",
+			target: agentType
+		});
+		this.server.setAutoStatus("thinking");
+	}
+	onSubagentStop(_payload) {
+		this.server.setActiveToolCall(null);
+	}
+	onStop() {
+		this.server.setAutoStatus(null);
+		this.server.setActiveToolCall(null);
+	}
+};
+
 //#endregion
 //#region packages/mcp/src/index.ts
 /**
@@ -22134,8 +22532,9 @@ async function main() {
 ## Key Concepts
 - Documents form a tree. A kanban board's columns are child documents; cards are grandchildren.
 - A document's label IS its display name everywhere. Children ARE the content (not just the body text).
-- Page types (doc, kanban, table, calendar, timeline, outline, etc.) are views over the SAME tree — switching types preserves data.
+- Page types (doc, kanban, table, calendar, timeline, checklist, outline, gallery, map, graph, dashboard, spatial, media, mindmap, etc.) are views over the SAME tree — switching types preserves data.
 - An empty markdown body does NOT mean empty content — always check the children array.
+- Use ![[docId]] in content to embed another document, or [[docId|label]] for inline links.
 
 ## Finding Documents
 - list_documents only shows ONE level of children. If you don't find what you need, use find_document to search the entire tree by name, or get_document_tree to see the full hierarchy.
@@ -22172,12 +22571,21 @@ Read the resource at abracadabra://agent-guide for the complete guide covering p
 		console.error(`[abracadabra-mcp] Failed to connect: ${error.message}`);
 		process.exit(1);
 	}
+	const hookBridge = new HookBridge(server);
+	try {
+		const hookPort = await hookBridge.start();
+		console.error(`[abracadabra-mcp] Hook bridge listening on port ${hookPort}`);
+	} catch (error) {
+		console.error(`[abracadabra-mcp] Hook bridge failed to start: ${error.message}`);
+	}
+	registerHookTools(mcp, hookBridge);
 	const transport = new StdioServerTransport();
 	await mcp.connect(transport);
 	server.startChannelNotifications(mcp);
 	console.error("[abracadabra-mcp] MCP server running on stdio");
 	const shutdown = async () => {
 		console.error("[abracadabra-mcp] Shutting down...");
+		await hookBridge.destroy();
 		await server.destroy();
 		process.exit(0);
 	};