drafted 1.19.5 → 1.19.7

package/install-mcp.sh

@@ -480,7 +480,7 @@ load_global_agent_instructions() {
   fi
   cat <<'DRAFTED_GLOBAL_INSTRUCTIONS'
 <drafted>
-You have Drafted MCP tools — a shared surface for durable, reviewable work: produce substantive output as frames on the surface (not only in chat), put knowledge in the org wiki, and encode repeatable methods as skills. The full operating manual is the `drafted` skill installed with the plugin — follow it when working with Drafted. Before writing, verify the org/project echoed in the response is the one you intend.
+You have Drafted MCP tools — a shared surface for durable, reviewable work: produce substantive output as frames on the surface (not only in chat), put knowledge in the org wiki, and encode repeatable methods as skills. The full operating manual is the `drafted` skill installed with the plugin — follow it when working with Drafted. Address orgs by path: `fs(ls, path="/")` lists them, and `/o/<org>/<root>/...` (root ∈ wiki, skills, projects) is the canonical path form — the org is part of the path, never a separate switch. Before writing, verify the org/project echoed in the response is the one you intend.
 </drafted>
 DRAFTED_GLOBAL_INSTRUCTIONS
 }

package/mcp/server.mjs

@@ -384,7 +384,7 @@ const TOOL_ANNOTATIONS = {
   auth:                { title: 'Sign in',             readOnlyHint: false, destructiveHint: false, openWorldHint: true,  description: 'Sign in to Drafted. `action=get_link` returns a URL immediately and starts background approval polling; after the user opens the link, later Drafted tool calls also auto-consume the approved login. `action=login` opens a browser when needed and explicitly waits/polls for approval.' },
 
   // Identity — read-only introspection of THIS agent's session
-  whoami:              { title: 'Session identity',    readOnlyHint: true,  destructiveHint: false, openWorldHint: false, description: 'Return THIS agent session\'s identity: its server-assigned human-readable name (the correlation key between an agent window and its web-app session tab), sessionId, userId, orgId, active projectId, editor label, server URL, and surfaced/alive state — PLUS server health and the installed MCP version/update status (cached ~5min). Call once per session, right after starting, so a required update surfaces before you act on stale tool behavior. Read-only. Use this — not guesses from the host environment — to report which session you are.' },
+  whoami:              { title: 'Session identity',    readOnlyHint: true,  destructiveHint: false, openWorldHint: false, description: 'Return THIS agent session\'s identity: its server-assigned human-readable name (the correlation key between an agent window and its web-app session tab), sessionId, userId, orgId, active projectId, editor label, server URL, and surfaced/alive state — PLUS server health, the installed MCP version/update status (cached ~5min), and `googleDrive` — whether the working org has Google Drive connected: when `googleDrive.connected` is true, strongly prefer Google Workspace frames (.google-doc/.google-sheet/.google-slide) for docs, sheets, and decks; when false they cannot be created at all. Call once per session, right after starting, so a required update surfaces before you act on stale tool behavior. Read-only. Use this — not guesses from the host environment — to report which session you are.' },
 
   // Session naming — the name-before-work gate: every agent session must set a short
   // name describing the work before any other tool call succeeds.
@@ -401,7 +401,7 @@ const TOOL_ANNOTATIONS = {
   // Minions — checklist-driven intake surfaces bound to a project
   minion:              { title: 'Minions',             readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Manage Minions: checklist-driven intake surfaces that guide a consumer through a checklist (via a shareable /c/<slug> link) and write a producible into the project. Dispatch by `action`: meta, list, get, create, update, enable, disable, delete. QA your own Minions with test_start/test_say/test_resolve — drive the checklist conversation yourself (works even when disabled). Requires the agent allowlist.' },
   trigger:             { title: 'Inbound triggers',    readOnlyHint: false, destructiveHint: true,  openWorldHint: true,  description: 'Manage inbound webhook triggers for the ACTIVE PROJECT: an external system (AppSheet bot, GitHub, form tool) POSTs to the trigger URL and the server runs an agent conversation in the project from the stored prompt template + payload. Dispatch by `action`: create (returns URL + secret token ONCE — relay it to the user immediately, not retrievable later), list, update (enable/disable, edit template, daily limit, executor), rotate (new token), test (fire a synthetic delivery), deliveries (audit log), delete; for executor="queue" triggers, pending/claim/complete let a LOCAL agent poll and work queued deliveries. Requires the agent allowlist.' },
-  fs:                  { title: 'Filesystem',           readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Navigate Drafted like a local filesystem: /wiki/<path> pages, /skills/<slug> procedures, /projects/<folder?>/<project>/<layer>/<lane>/<file> frames. Verbs: ls, read, write, edit, mv, rm, search.' },
+  fs:                  { title: 'Filesystem',           readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Navigate Drafted like a local filesystem: /wiki/<path> pages, /skills/<slug> procedures, /projects/<folder?>/<project>/<layer>/<lane>/<file> frames. Verbs: ls, read, write, edit, mv, rm, search, link, unlink, links.' },
   repo:                { title: 'Git repos',           readOnlyHint: false, destructiveHint: true,  openWorldHint: true,  description: 'Registered git repos — the org index of .agents/ skills + identities. A connected repo is the source of truth for its skills; EVERY repo connected to ANY folder in the org is searchable and usable org-wide (no org-level repo — the union is the library). Skills from connected repos are readable via fs(read, path="/skills/<slug>") — fetched from git at read time, always fresh. Authoring a Drafted skill whose slug collides with a repo-indexed skill returns 409 repo_owned pointing at the repo. Dispatch by `action`: list (paginated, compact mode), add (link a repo to a folder, --branch optional), rescan (re-fetch the tracked branch), entries (search the index). Content stays in git; Drafted keeps a read-only index.' },
 };
 
@@ -413,7 +413,7 @@ function isMutatingToolCall(name, args = {}) {
     case 'trigger':
       return ['create', 'update', 'rotate', 'delete'].includes(action);
     case 'fs':
-      return !['ls', 'read', 'search'].includes(action);
+      return !['ls', 'read', 'search', 'links'].includes(action);
     default:
       return false;
   }
@@ -2261,17 +2261,37 @@ async function sessionSurfaceBlock() {
   };
 }
 
+// Is the working org's Drive connected? Agents are told to prefer Google Workspace frames
+// when it is, so they need a way to ASK — this rode on `get_org` until that tool was retired
+// (DRAFT-36), leaving agents to probe by attempting a .google-doc write and reading the 400.
+// Rides on whoami, the once-per-session bootstrap that replaced it. Never throws: an
+// unreachable/erroring status is reported as not-connected, same as no connection.
+async function getGoogleDriveAvailability() {
+  try {
+    const status = await api('GET', '/api/google/status');
+    return {
+      connected: !!status?.connected,
+      driveRootFolderName: status?.driveRootFolderName || null,
+      preference: status?.connected
+        ? 'Google Drive is connected for this org — strongly prefer Google Workspace frames (.google-doc / .google-sheet / .google-slide) for docs, sheets, and decks.'
+        : 'Google Drive is not connected for this org — use normal Drafted frames (.md / .html); Google Workspace writes will fail.',
+    };
+  } catch {
+    return { connected: false, driveRootFolderName: null, preference: 'Google Drive status unavailable — use normal Drafted frames.' };
+  }
+}
+
 // Identity + server health: report THIS agent session's own surface identity, server
 // reachability, and installed-MCP staleness in ONE bootstrap call. The update data is
 // cached (5min), so repeat `whoami` calls are free; the server-side update gate still
 // blocks mutating calls on its own, independent of this tool. Read-only — no state changed.
-tool('whoami', 'Return THIS agent session\'s identity: its server-assigned human-readable name (the correlation key between an agent window and its web-app session tab), sessionId, userId, orgId, active projectId, editor label, server URL, and surfaced/alive state — PLUS server health and the installed MCP version/update status (cached ~5min). Call once per session, right after starting, so a required update surfaces before you act on stale tool behavior. Read-only.', {}, async () => {
+tool('whoami', 'Return THIS agent session\'s identity: its server-assigned human-readable name (the correlation key between an agent window and its web-app session tab), sessionId, userId, orgId, active projectId, editor label, server URL, and surfaced/alive state — PLUS server health, the installed MCP version/update status (cached ~5min), and `googleDrive` — whether the working org has Google Drive connected: when `googleDrive.connected` is true, strongly prefer Google Workspace frames (.google-doc/.google-sheet/.google-slide) for docs, sheets, and decks; when false they cannot be created at all. Call once per session, right after starting, so a required update surfaces before you act on stale tool behavior. Read-only.', {}, async () => {
   try {
     // Ensure the child clone exists BEFORE reading identity — otherwise the /auth/me
     // fallback (pre-WS-ack) queries the ROOT session and reports the wrong naming state.
     await ensureSession();
     const block = await sessionSurfaceBlock();
-    const mcpUpdate = await getCachedMcpUpdateMetadata();
+    const [mcpUpdate, googleDrive] = await Promise.all([getCachedMcpUpdateMetadata(), getGoogleDriveAvailability()]);
     // Tell the agent to actually surface its name to the user — returning `name` in the JSON isn't
     // enough; without an explicit instruction agents rarely say which session they are, so users
     // can't match them to their tab on the Drafted surface.
@@ -2287,6 +2307,7 @@ tool('whoami', 'Return THIS agent session\'s identity: its server-assigned human
       mcpUpdate,
       editor: (process.env.DRAFTED_AGENT_NAME || '').trim() || null,
       agentLabel: getAgentLabel(),
+      googleDrive,
       ...block,
       ...(instruction ? { instruction } : {}),
     });
@@ -2802,10 +2823,11 @@ server.resource('info', 'drafted://info', {
   };
 });
 
-tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder: `fs(ls, path="/")` lists the orgs you can address, then `/o/<org>/<root>/...` addresses one of them — the org is part of the path, there is no org switching:\n\n- `/o/<org>/wiki/<path>` — org knowledge pages (markdown, OKF; free nesting; `index.md` at any level is synthesized and read-only)\n- `/o/<org>/skills/<slug>` — reusable procedures (flat: one dir per skill slug, `SKILL.md` + supporting files inside)\n- `/o/<org>/tasks/<lane?>/<file>` — work items. A task IS a frame: `read` renders its `drafted:status:`/`drafted:assignee:` as front matter and `write`/`edit` parse them back into columns, so they are never stored in the body. The keys are namespaced so an ordinary `status:` in your own front matter is left alone. Valid statuses: open, in_progress, scheduled, needs_review, needs_decision, done, failed (an empty `drafted:status:` clears it). Status is a column, not a location — a task moved out of /tasks stays a task.\n- `/o/<org>/projects/<folder?>/<project>/<layer>/<lane>/<file>` — producible frames (folder optional; then exactly layer → lane → file)\n\n(Bare `/wiki`, `/skills`, `/tasks`, `/projects` roots still resolve via the session\'s working org.)\n\nVerbs: `ls` (list a directory), `read` (file content — hashline-annotated for text so `edit` stays surgical), `write` (create/overwrite; extension + layer classify the type: .html design, .md document, .excalidraw diagram, .xlsx/.docx office, images/videos media, .pdf asset, .google-doc/.google-sheet/.google-slide create native Google Workspace files), `edit` (hashline ops for text, element ops for excalidraw, structured ops for office), `mv` (rename/move, cross-project), `rm` (delete), `search` (frames are searched by label AND content, with the matching line returned as a snippet; `fs(search, path="/")` or `path="/o/<org>"` fans out across wiki + skills + projects in one call). `mkdir` creates a project only: use `/projects/<project>` or `/projects/<folder>/<project>`, never a layer path. To create a layer, write its first frame at `/projects/<project>/<new-layer>/<lane>/<file>`.\n\nThe project is resolved from the path itself — no separate "open" step. Guardrails are server-side and unchanged: the org in the path must be the project\'s own org (project paths under /o/<org>/ validate it), the G1 wiki-search gate fires before project mutations, attached-skill gates fire on mutations, anchored frames must be read before editing a layer, `.skillinstall/` is stripped on skill push.', {
-  action: z.enum(['ls', 'read', 'write', 'edit', 'mv', 'rm', 'mkdir', 'search']).describe('Filesystem verb.'),
+tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder: `fs(ls, path="/")` lists the orgs you can address, then `/o/<org>/<root>/...` addresses one of them — the org is part of the path, there is no org switching:\n\n- `/o/<org>/wiki/<path>` — org knowledge pages (markdown, OKF; free nesting; `index.md` at any level is synthesized and read-only)\n- `/o/<org>/skills/<slug>` — reusable procedures (flat: one dir per skill slug, `SKILL.md` + supporting files inside)\n- `/o/<org>/tasks/<lane?>/<file>` — work items. A task IS a frame: `read` renders its `drafted:status:`/`drafted:assignee:` as front matter and `write`/`edit` parse them back into columns, so they are never stored in the body. The keys are namespaced so an ordinary `status:` in your own front matter is left alone. Valid statuses: open, in_progress, scheduled, needs_review, needs_decision, done, failed (an empty `drafted:status:` clears it). Status is a column, not a location — a task moved out of /tasks stays a task.\n- `/o/<org>/projects/<folder?>/<project>/<layer>/<lane>/<file>` — producible frames (folder optional; then exactly layer → lane → file)\n\n(Bare `/wiki`, `/skills`, `/tasks`, `/projects` roots still resolve via the session\'s working org.)\n\nVerbs: `ls` (list a directory), `read` (file content — hashline-annotated for text so `edit` stays surgical), `write` (create/overwrite; extension + layer classify the type: .html design, .md document, .excalidraw diagram, .xlsx/.docx office, images/videos media, .pdf asset, .google-doc/.google-sheet/.google-slide create native Google Workspace files), `edit` (hashline ops for text, element ops for excalidraw, structured ops for office), `mv` (rename/move, cross-project), `rm` (delete), `search` (frames are searched by label AND content, with the matching line returned as a snippet; `fs(search, path="/")` or `path="/o/<org>"` fans out across wiki + skills + projects in one call), `link` / `unlink` / `links` (relate one frame to another frame, to a project, or to an external url — `links` lists a frame\'s edges plus its backlinks, and on a project path lists the tasks linked to that project; a link is stored by ID, so `mv` never breaks it). `mkdir` creates a project only: use `/projects/<project>` or `/projects/<folder>/<project>`, never a layer path. To create a layer, write its first frame at `/projects/<project>/<new-layer>/<lane>/<file>`.\n\nThe project is resolved from the path itself — no separate "open" step. Guardrails are server-side and unchanged: the org in the path must be the project\'s own org (project paths under /o/<org>/ validate it), the G1 wiki-search gate fires before project mutations, attached-skill gates fire on mutations, anchored frames must be read before editing a layer, `.skillinstall/` is stripped on skill push.', {
+  action: z.enum(['ls', 'read', 'write', 'edit', 'mv', 'rm', 'mkdir', 'search', 'link', 'unlink', 'links']).describe('Filesystem verb.'),
   path: z.string().describe('Drafted path: /o/<org>/wiki/... | /o/<org>/skills/... | /o/<org>/tasks/... | /o/<org>/projects/... (bare /wiki, /skills, /tasks, /projects also work; for mv: source)'),
-  to: z.string().optional().describe('[mv] destination path'),
+  to: z.string().optional().describe('[mv] destination path; [link/unlink] target path — a frame path, or a project path (/o/<org>/projects/<project>) to link a task to a project'),
+  url: z.string().optional().describe('[link/unlink] external target URL, instead of `to` (a link is internal-by-id OR external-by-url, never both)'),
   query: z.string().optional().describe('[search] term to match against names/content'),
   content: z.string().optional().describe('[write] inline HTML/markdown/text'),
   file_path: z.string().optional().describe('[write] absolute path to a local file to upload (stdio only). Under /projects it uploads bytes (images, PDFs, office files); under /wiki and /skills it reads the file as UTF-8 text, so a markdown file on disk can be written straight to a page or a SKILL.md without pasting it.'),
@@ -2840,10 +2862,10 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
     const toScoped = splitOrgScope(stripUrlOrigin(to));
     if (toScoped.error) return err(new Error(toScoped.error));
     if (toScoped.org && orgFromPath && toScoped.org.toLowerCase() !== orgFromPath.toLowerCase()) {
-      return err(new Error('mv stays within one org — source and destination must address the same org'));
+      return err(new Error(`${action} stays within one org — source and destination must address the same org`));
     }
     if (toScoped.org && !orgFromPath) {
-      return err(new Error('mv to an org-scoped destination needs an org-scoped source too (/o/<org>/... on both sides)'));
+      return err(new Error(`${action} to an org-scoped destination needs an org-scoped source too (/o/<org>/... on both sides)`));
     }
     to = toScoped.path;
   }
@@ -3159,7 +3181,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
   // so a task moved out of here stays a task.
   const isTasksPath = (x) => x === '/tasks' || x === '/tasks/' || String(x || '').startsWith('/tasks/');
   if (isTasksPath(p) || isTasksPath(to)) {
-    if (['write', 'edit', 'mv', 'rm'].includes(action)) {
+    if (['write', 'edit', 'mv', 'rm', 'link', 'unlink'].includes(action)) {
       // Project-less: the org cannot be guessed (same guard as /wiki and /skills).
       await requireBoundOrgForProjectlessMutation(org || orgFromPath);
     }
@@ -3171,7 +3193,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
     // `fs(ls, path="/tasks")` creating one would put a real "Tasks" project in
     // an org the agent never named (DRAFT-36: org is an address, not a guess).
     // Writes are guarded above and may create; reads say "nothing here yet".
-    const readOnly = !['write', 'edit', 'mv', 'rm'].includes(action);
+    const readOnly = !['write', 'edit', 'mv', 'rm', 'link', 'unlink'].includes(action);
     const sys = await api('POST', '/api/tasks/project', readOnly ? { create: false } : {}, orgHeader)
       .catch((e) => (readOnly && e.status === 404 ? null : Promise.reject(e)));
     if (!sys?.id) {
@@ -3458,6 +3480,51 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
           const result = await api('DELETE', `/api/fs/${rmPath.replace(/^\//, '')}`, undefined, orgHeader);
           return ok(result);
         }
+        case 'link':
+        case 'unlink': {
+          if (!filePath) return err(new Error(`${action} requires a source file path: /projects/<project>/<layer>/<lane>/<file>`));
+          const from = lane ? `/${layer}/${lane}/${filename}` : `/${layer}/${filename}`;
+          const body = { from };
+          if (args.url) {
+            body.url = args.url;
+          } else if (to) {
+            // Same destination grammar as mv: /projects/<ref>/<layer>/... is a
+            // frame in another project, /projects/<ref> alone is the project
+            // itself (the "this task belongs to that project" edge), and a bare
+            // /<layer>/... is a frame in this one.
+            const toClean = String(to).replace(/^\/+|\/+$/g, '');
+            const toParts = toClean.replace(/^projects\/?/, '').split('/').filter(Boolean);
+            if (toClean.startsWith('projects/') && toParts.length === 1) {
+              const toMeta = await resolveProjectRef(toParts[0]).catch(() => null);
+              if (!toMeta?.id) return err(new Error(`project not found: ${toParts[0]}`));
+              body.toType = 'project';
+              body.toId = toMeta.id;
+            } else if (toClean.startsWith('projects/') && toParts.length >= 2) {
+              const toRef = toParts[0];
+              const sameProject = projectRef && String(toRef).toLowerCase() === String(projectRef).toLowerCase();
+              if (!sameProject) {
+                const toMeta = await resolveProjectRef(toRef).catch(() => null);
+                if (!toMeta?.id) return err(new Error(`project not found: ${toRef}`));
+                body.toProjectId = toMeta.id;
+              }
+              body.to = '/' + toParts.slice(1).join('/');
+            } else {
+              body.to = toParts.length ? '/' + toParts.join('/') : String(to);
+            }
+          } else {
+            return err(new Error(`${action} needs a target: to="<frame or project path>" or url="https://..."`));
+          }
+          return ok(await api('POST', `/api/fs/${action}`, body, orgHeader));
+        }
+        case 'links': {
+          // On a file: its edges plus its (access-filtered) backlinks. On a
+          // project path: the tasks linked to that project.
+          if (filePath) {
+            const relPath = lane ? `/${layer}/${lane}/${filename}` : `/${layer}/${filename}`;
+            return ok(await api('GET', `/api/fs/links?path=${encodeURIComponent(relPath)}`, undefined, orgHeader));
+          }
+          return ok(await api('GET', '/api/fs/linked-tasks', undefined, orgHeader));
+        }
         case 'search': {
           // /api/fs/search has never existed — this 404'd on every call (no fs
           // route matches a single `/search` segment). /api/search is the real

package/package.json

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

package/plugin/skills/drafted/SKILL.md

@@ -65,7 +65,7 @@ These bookend the loop. Prime/feed at the start, deposit at the end.
 - **Create a project with `fs(mkdir, path="/o/<org>/projects/<name>")`** — or just `fs(write, path="/o/<org>/projects/<name>/<layer>/<lane>/<file>", content=...)` and the project + layer auto-create in the addressed org.
 - **Default to the surface for substantive artifacts.** When asked to draft, write, plan, analyze, compare, design, document, summarize, report, spec, model, or make a deck/table, create or update frames instead of leaving the durable result only in chat. One visible frame per artifact or section.
 - **Read before editing.** `fs(read)` returns every line hashline-annotated (`1abc|<content>`); `fs(edit, ops=[{type:"replace", lineHash:"1abc", newContent:"..."}])` targets exactly that line. For partial reads, pass `lines: "2-50"` — you get back just that range, still hash-annotated, and can edit within it.
-- **Prefer Google Workspace when Drive is connected.** Use `fs(write, path=".../<name>.google-doc"|".google-sheet"|".google-slide")` for docs, sheets, and decks; populate immediately with the matching native write action.
+- **Prefer Google Workspace when Drive is connected.** `whoami` reports it — `googleDrive.connected: true` means use `fs(write, path=".../<name>.google-doc"|".google-sheet"|".google-slide")` for docs, sheets, and decks, populated immediately with the matching native write action. False means they cannot be created at all: use `.md`/`.html` frames and don't ask the user which fallback they want.
 - **`fs(mv, from="/o/<org>/projects/<p>/<layer>/<lane>/<file>", to="...")`** renames or moves (cross-project too). **`fs(rm, path="/o/<org>/projects/<project>")` archives** — agents never hard-delete; the archive is in the web UI.
 - **Return a clickable link** for what you touched — the `frameUrl`/`projectUrl` in the fs response is the URL the user opens.