drafted 1.14.13 → 1.14.15

package/README.md

@@ -13,7 +13,19 @@ Drafted is a native producer and consumer of the **Open Knowledge Format (OKF) v
 - **The org wiki is an OKF v0.1 bundle.** Every page carries conformant YAML frontmatter (required `type`, one-line `description`, `tags`, synthesized `timestamp`; unknown keys preserved). `index.md` at every level is synthesized, `log.md` keeps the date-grouped change history, links resolve with or without `.md`, and broken links are legal. The wiki UI shows a live OKF conformance badge.
 - **Bundle exchange everywhere.** Export/import the wiki (`GET /api/wiki/export.tar.gz`, `POST /api/wiki/import`), the skill library (`skills/<slug>/SKILL.md` layout), and whole projects (`<layer>/<lane>/<file>.md` concepts; markdown links round-trip as connectors) — via HTTP or the MCP `wiki`, `skill`, and `project` tools, with dry-run reports.
 
-## Quick start
+## Install
+
+**Claude Code, Cursor, or any MCP client:**
+
+```bash
+claude mcp add drafted
+```
+
+**Claude on the web (claude.ai) and Cowork** — install the plugin, not the bare connector. The plugin bundles the Drafted connector *plus* the Drafted skill and the eight slash commands (`/drafted:onboard-drafted`, `/drafted:create-project`, `/drafted:create-skill`, `/drafted:ingest`, `/drafted:extract`, `/drafted:improve-wiki`, `/drafted:improve-skill`, `/drafted:improve-project-harness`); adding the connector URL on its own gives you the tools with none of the guidance.
+
+> Settings → Customize plugins → Add → Add marketplace → `ddfourtwo/drafted-web` → install **Drafted** → sign in when prompted.
+
+## Quick start (developing Drafted itself)
 
 ```bash
 npm install && npm run dev   # Docker services + schema + server with hot reload

package/mcp/server.mjs

@@ -222,7 +222,9 @@ IMPORTANT: Any URL containing /f/{uuid} is a Drafted frame link — ALWAYS use r
   // tab name + the right way to read it WITHOUT having to "think to" call a tool.
   instructions: `SESSION IDENTITY — read this first: you run as a NAMED session tab visible to the user on their Drafted surface. Your session has a human-readable name (a Greek term, e.g. "Nous") — that name is how the user matches YOUR window to the tab they see, so identify yourself by it when it matters which agent you are. Read it from get_org (response field "session.name") or from the whoami tool; call whoami to refresh after a reconnect.
 
-DUAL REGISTRATION IS NORMAL: a separate "Drafted" remote connector (https://drafted.live/mcp, managed by claude.ai) may appear alongside this local stdio server in MCP listings. It is NOT a duplicate and NOT broken — it serves claude.ai web/mobile/Cowork, where a local stdio process cannot run. Never advise removing it; a "needs authentication" state on it is fixed by signing in from claude.ai and does not affect this stdio session.`,
+DUAL REGISTRATION IS NORMAL: a separate "Drafted" remote connector (https://drafted.live/mcp, managed by claude.ai) may appear alongside this local stdio server in MCP listings. It is NOT a duplicate and NOT broken — it serves claude.ai web/mobile/Cowork, where a local stdio process cannot run. Never advise removing it; a "needs authentication" state on it is fixed by signing in from claude.ai and does not affect this stdio session.${isRemote ? `
+
+PLUGIN vs BARE CONNECTOR: Drafted ships as a plugin that bundles these tools WITH the Drafted skill and eight slash commands (/drafted:onboard-drafted, /drafted:create-project, /drafted:create-skill, /drafted:ingest, /drafted:extract, /drafted:improve-wiki, /drafted:improve-skill, /drafted:improve-project-harness). If the user added only the connector URL, they have the tools but none of that — the guidance for HOW to use the surface well is in the skill and commands they are missing. If the user asks where the slash commands are, or seems to be missing Drafted guidance, tell them: Settings → Customize plugins → Add → Add marketplace → ddfourtwo/drafted-web → install Drafted, then sign in when prompted. Mention it once, do not nag.` : ''}`,
 });
 
 const layerKeys = Object.keys(LAYERS);
@@ -1460,11 +1462,12 @@ async function requireBoundOrgForProjectlessMutation(explicitOrg) {
       `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 in ONE call:\n` +
-      `  • get_org(action="use", org="<name>") — binds this session's working org; every ` +
-      `later project-less wiki/skill write then just works, no project needed.\n` +
-      `  • or pass org="<name>" on this single call.\n` +
-      `  • or project(action="open") if the work belongs to a project — the org derives from it.\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.`
     );
   }
@@ -1863,6 +1866,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.
@@ -2671,7 +2680,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.'),
@@ -3178,8 +3187,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);
@@ -3194,6 +3204,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()}`);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.14.13",
+  "version": "1.14.15",
   "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": [