drafted 1.14.12 → 1.14.14

package/mcp/server.mjs

@@ -1450,12 +1450,23 @@ async function requireBoundOrgForProjectlessMutation(explicitOrg) {
     return;
   }
   if (projectlessMutationNeedsOrg({ orgCount: orgs.length })) {
+    // Actionable, not a dead end: name the orgs and the ONE call that binds this session,
+    // so the agent recovers itself instead of stalling on the human. Project-less wiki and
+    // skill work is a first-class flow — no project required, ever. The only thing refused
+    // is GUESSING which org, which is what silently misfiled a page into the user's
+    // default org. (Listing the orgs is safe: they're the caller's own memberships.)
+    const names = orgs.map(o => o.name || o.id).filter(Boolean);
     throw new Error(
-      `Refusing to guess the org: no project is open and no explicit org was ` +
-      `given, but you belong to ${orgs.length} orgs — a project-less wiki/skill write ` +
-      `would land in whichever org the session inherited. Pass org=... on this ` +
-      `call (org name or id), or open the relevant project first ` +
-      `(project(action="open") — the org derives from the project).`
+      `Which org? A project-less wiki/skill write needs one, and you belong to ${orgs.length}: ` +
+      `${names.join(', ')}. Don't guess — an unaddressed write lands in whichever org this ` +
+      `session inherited, which is how a page meant for one org ends up in another.\n` +
+      `Recover with ONE call: get_org(action="use", org="<name>"). That binds this session's ` +
+      `working org — every later project-less wiki/skill write then just works, with no project ` +
+      `and no org= to repeat. Prefer it over passing org= per call, which pays this toll on ` +
+      `every write.\n` +
+      `(Alternatives: org="<name>" on this single call; or project(action="open") if the work ` +
+      `belongs to a project — the org derives from it.)\n` +
+      `Pick from the conversation if the org is clear from context; ask the user only if it isn't.`
     );
   }
 }
@@ -1853,6 +1864,12 @@ async function sessionSurfaceBlock() {
       color: agentSurface.color,
       surfaced: true,
       alive: !!agentSurface.alive,
+      // `alive` was ambiguous: agents couldn't tell whether it meant "your writes are
+      // no-ops" (act differently) or "the user's canvas tab is closed" (ignore). It's the
+      // latter — say so, so nobody changes behavior over it.
+      aliveMeaning: agentSurface.alive
+        ? 'A canvas/desktop surface is live for this session — focus and presence calls will be seen.'
+        : 'No canvas surface is currently open for this session. Frame, wiki, and skill writes all persist normally — only focus/presence have nothing to draw on. Do not change what you write because of this.',
     };
   }
   // No WS ack yet — best-effort identity from /auth/me so callers still get a userId/org.
@@ -2661,7 +2678,7 @@ tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by
   path: z.string().optional().describe('[read] /{layer}/{lane}/{filename}, frame URL, or UUID. [write|edit|anchor] /{layer}/{lane}/{filename}.'),
   lines: z.string().optional().describe('[read] line range (e.g. "1-50"). Omit to read all.'),
   content: z.string().optional().describe('[write] HTML/markdown/text for Drafted inline frames. [write_doc_content|append_doc_content] native Google Doc body text. Do not use action=write content to populate Google Doc/Slide frames.'),
-  excalidraw_data: z.any().optional().describe('[write_excalidraw] Excalidraw scene JSON object or JSON string. Defaults to an empty scene.'),
+  excalidraw_data: z.any().optional().describe('[write_excalidraw] Excalidraw scene JSON object or JSON string. Defaults to an empty scene. WRITE LEAN SCENES: your MCP client caps tool-call arguments (a big scene is rejected before Drafted ever sees it), so emit only the fields that carry meaning — id, type, x, y, width, height, angle, text/label, strokeColor, backgroundColor, fillStyle, strokeWidth, and the binding ids for arrows. Omit every field the editor can default (version, versionNonce, seed, updated, groupIds, boundElements when empty, roundness, opacity at 100, frameId when null). The editor fills them on open; shipping them can triple the payload for no gain. For a big diagram, write it in passes: create the scene, then frame(action="write_excalidraw") again with the next batch of elements.'),
   state: z.any().optional().describe('[set_state] App-frame state object (JSON) to persist for a deployed windowType:"app" frame — e.g. {specText:"..."} for the AS/NZS electrical app. The canvas hydrates the app from this on load (the host posts a "hydrate" message with it when the frame mounts), so you can deploy a generic app frame once and drive it with data afterwards. Max 64KB. Frame must be an app frame.'),
   file_path: z.string().optional().describe('[write] absolute path to a local file to upload. Mutually exclusive with content/base64/googleType.'),
   base64: z.string().optional().describe('[write] base64-encoded binary content. Mutually exclusive with content/file_path/googleType. Use with content_type when known.'),
@@ -3168,8 +3185,9 @@ tool('ls', 'List contents of the ACTIVE PROJECT. Use ls / after project(action="
   recursive: z.boolean().optional().describe('List contents of subdirectories. When true, forces summary mode (metadata only, no full content) to keep results under the 25k token cap.'),
   summary: z.boolean().optional().describe('Include size, updatedAt, title for frames'),
   pattern: z.string().optional().describe('Glob pattern to filter filenames (e.g. "*.html")'),
+  head: z.number().optional().describe('Include the first N lines of EACH frame inline (max 50). Survey a whole lane in one call instead of one frame(action="read") per frame — read only the frames the heads show you actually need.'),
   limit: z.number().optional().default(500).describe('Max entries to return (default 500, max 2000). Use pattern or path to scope further.'),
-}, async ({ path, recursive, summary, pattern, limit }) => {
+}, async ({ path, recursive, summary, pattern, head, limit }) => {
   try {
     const params = new URLSearchParams();
     params.set('path', path);
@@ -3184,6 +3202,7 @@ tool('ls', 'List contents of the ACTIVE PROJECT. Use ls / after project(action="
     } else if (summary) {
       params.set('summary', 'true');
     }
+    if (head) params.set('head', String(head));
     if (pattern) params.set('pattern', pattern);
     const result = await api('GET', `/api/fs/?${params.toString()}`);
 
@@ -3548,7 +3567,7 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
   path: z.string().optional().describe('[read_file|update_file] relative path inside skill directory (e.g. "examples/react.md")'),
   offset: z.number().optional().describe('[search|list|export] skip N results for pagination; [read_file] start reading at this byte offset (default 0) — for large files (e.g. a >90KB app-frame bundle) read in chunks using the returned nextOffset until truncated=false'),
   maxBytes: z.number().optional().describe('[read_file] return at most this many bytes from offset (default: whole remaining file). Response reports totalSize/offset/truncated/nextOffset.'),
-  org: z.string().optional().describe('[add] org (id or name) the skill is born in — defaults to the open project\'s org; [list|search|load] scope to this org; [fork|push|update|export|import] resolve/fork into this org. Per-request only — nothing is switched.'),
+  org: z.string().optional().describe('[add] org (id or name) the skill is born in — defaults to the open project\'s org; [list|search|load] scope to this org; [fork|push|update|export|import] resolve/fork into this org. Per-request only — nothing is switched. NO PROJECT IS NEEDED: for project-less skill work either pass org= here, or bind the session once with get_org(action="use", org="<name>"). A multi-org caller that addresses neither is refused rather than guessed.'),
   setup: z.array(z.string()).optional().describe('[add|update] setup command(s) (in order) run on materialize to build a source-only skill, e.g. ["npm ci","npm run build"]'),
   files: z.array(z.object({ path: z.string(), content: z.string() })).optional().describe('[push] source files to push (path + UTF-8 content); server strips artifacts + enforces caps. [import] OKF bundle files inline — skills/<slug>/SKILL.md dirs and Skill/Playbook/SOP/Procedure-typed .md with name + description frontmatter become org skills. Caps: 500 files, 512KB/file, 5MB total.'),
   dir: z.string().optional().describe('[push|export|import] local directory. push: source tree to push instead of files[]; walked locally (heavy dirs, .skillinstall/, and .skillignore pre-filtered), server re-enforces; the dir\'s .gitignore is auto-updated to exclude .skillinstall/ (the rebuildable bundle). export: write the OKF bundle files here (default ./okf-skills-<org>). import: read the bundle from here (alternative to files[]).'),
@@ -3846,7 +3865,7 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
   action: z.enum(['ls', 'recent', 'read', 'search', 'links', 'log', 'health', 'write', 'edit', 'mv', 'rm', 'cite', 'source-register', 'source-list', 'source-get', 'bulk-write', 'export', 'import']).describe('Operation to perform. export: the whole wiki as an OKF v0.1 bundle (local dir on stdio, download URL on remote, or format="files" for paged inline files). import: ingest an OKF bundle (files[] or local dir; dryRun supported).'),
   path: z.string().optional().describe('[ls|read|links|cite] wiki path. For ls: default / (root). For read: required. For links/cite: required unless pageId given. Reading `index.md` (any level) returns the SYNTHESIZED OKF directory listing.'),
   pageId: z.string().optional().describe('[read|edit|mv|rm|links] page UUID (from read/search). UUID-first: addresses the page directly, org auto-derives — no org needed and no path lookup. Preferred over path for an existing page.'),
-  org: z.string().optional().describe('Org slug or id to scope this call to (per-request only — nothing is switched). [write] the org the page is created in — required when you belong to several orgs and no project is open. [search] restrict to this org (default: ALL your orgs). [ls|recent|read|links|log|health|edit|mv|rm|bulk-write] target this org\'s wiki instead of the open project\'s org. Ignored when a pageId is given (the page self-derives its org).'),
+  org: z.string().optional().describe('Org slug or id to scope this call to (per-request only — nothing is switched). NO PROJECT IS NEEDED for wiki work: to write project-less, either pass org= here, or bind the session once with get_org(action="use", org="<name>") and then omit it. Multi-org callers MUST address the org one of those two ways — an unaddressed write is refused rather than guessed (it would land in whichever org the session inherited). [write] the org the page is created in. [search] restrict to this org (default: ALL your orgs). [ls|recent|read|links|log|health|edit|mv|rm|bulk-write] target this org\'s wiki instead of the open project\'s org. Ignored when a pageId is given (the page self-derives its org).'),
   recursive: z.boolean().optional().describe('[ls] list recursively with depth indicators'),
   limit: z.number().optional().describe('[recent|search|export] max results (recent default 10, search default 25, export files default 100)'),
   offset: z.number().optional().describe('[export] pagination offset for format="files"'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.14.12",
+  "version": "1.14.14",
   "description": "Drafted — visual thinking surface for humans and AI agents. Renders HTML, markdown, images, and code as frames on a zoomable canvas, with MCP tools for AI agents and real-time sync for humans.",
   "type": "module",
   "files": [