passalong 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Hand tasks, bugs and finished work to AI coding agents, and get back a write-up with evidence.",
   "mcpName": "io.github.codellyson/passalong",
   "keywords": [

package/src/api.js

@@ -301,10 +301,13 @@ export const join = (code) =>
   call(`/v1/invites/${encodeURIComponent(code)}/accept`, { method: "POST" });
 
 export const board = () => call("/v1/board");
-export const folders = (scope = "all") => call(`/v1/folders${q({ scope })}`);
-export const createFolder = (title, description = "", team = "") =>
-  call("/v1/folders", { method: "POST", body: { title, description, team } });
+export const folders = (scope = "all", { query = "", guide = "" } = {}) =>
+  call(`/v1/folders${q({ scope, q: query, guide })}`);
+export const createFolder = (title, description = "", team = "", parent = "", color = "") =>
+  call("/v1/folders", { method: "POST", body: { title, description, team, parent, color } });
 export const folder = (id) => call(`/v1/folders/${encodeURIComponent(id)}`);
+export const updateFolder = (id, changes) =>
+  call(`/v1/folders/${encodeURIComponent(id)}`, { method: "PATCH", body: changes });
 export const folderDocument = (folderId, documentId) =>
   call(`/v1/folders/${encodeURIComponent(folderId)}/documents/${encodeURIComponent(documentId)}`);
 export const folderAsset = (folderId, assetId) =>
@@ -329,8 +332,29 @@ export const saveFolderDocument = (folderId, documentId, version, body) =>
     method: "PUT",
     body: { version, body },
   });
+export const renameFolderDocument = (folderId, documentId, name) =>
+  call(`/v1/folders/${encodeURIComponent(folderId)}/documents/${encodeURIComponent(documentId)}`, {
+    method: "PATCH",
+    body: { name },
+  });
+export const folderDocumentHistory = (folderId, documentId, version = 0) =>
+  call(
+    `/v1/folders/${encodeURIComponent(folderId)}/documents/${encodeURIComponent(documentId)}/revisions${version ? `/${version}` : ""}`,
+  );
 export const linkFolderGuide = (folderId, guide) =>
   call(`/v1/folders/${encodeURIComponent(folderId)}/guides`, { method: "POST", body: { guide } });
+export const unlinkFolderGuide = (folderId, guide) =>
+  call(`/v1/folders/${encodeURIComponent(folderId)}/guides/${encodeURIComponent(guide)}`, {
+    method: "DELETE",
+  });
+export const deleteFolderDocument = (folderId, documentId) =>
+  call(`/v1/folders/${encodeURIComponent(folderId)}/documents/${encodeURIComponent(documentId)}`, {
+    method: "DELETE",
+  });
+export const deleteFolderAsset = (folderId, assetId) =>
+  call(`/v1/folders/${encodeURIComponent(folderId)}/assets/${encodeURIComponent(assetId)}`, {
+    method: "DELETE",
+  });
 /** What you did, newest first. `since` is a date prefix: 2026, 2026-09, 2026-09-11. */
 export const log = ({ repo = "", since = "", limit = 0 } = {}) =>
   call(`/v1/log${q({ repo, since, limit: limit || "" })}`);

package/src/mcp.js

@@ -219,6 +219,8 @@ const passOut = openObject({ id: z.string(), passed: z.boolean() });
 
 const READS = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
 const ADDS = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+// Removes something that cannot be brought back. Only a person's request should lead here.
+const REMOVES = { readOnlyHint: false, destructiveHint: true, openWorldHint: false };
 const fail = (err) => ({ content: [{ type: "text", text: err.message }], isError: true });
 
 /**
@@ -347,6 +349,8 @@ export function buildServer() {
         "FOLDERS ARE REUSABLE PROJECT CONTEXT, NOT GUIDES. When the user asks for a folder for a " +
         "script, brief, assets or work spanning several guides, call list_folders first to avoid " +
         "making a duplicate. If none fits, call create_folder with a title and short description. " +
+        "Use its parent id to nest a subfolder at any depth; keep a related project together. " +
+        "A folder's color can mark an area, and update_folder can recolor or move it later. " +
         "A short request is enough: name it from the person's purpose and draft the first Markdown " +
         "document with create_folder_document. Do not leave an empty folder or make them fill a form. " +
         "Pass `team` only when the user wants it shared with that team; use the slug they named " +
@@ -355,8 +359,16 @@ export function buildServer() {
         "get_folder_document to read text and its version, and save_folder_document with that " +
         "version when editing. On a stale-version refusal, reread before retrying so another " +
         "person's work is not lost. Use add_folder_asset for a screenshot or file available on " +
-        "this machine, get_folder_asset to read one already there, and link_folder_guide only " +
-        "when an existing guide uses that folder.\n" +
+        "this machine, and get_folder_asset to read one already there. " +
+        "To put a guide in a folder — a task, bug or handoff, new or already published — publish it " +
+        "as usual (for a team folder, to that folder's team, or its members cannot see it), then call " +
+        "link_folder_guide with the folder id and the guide id. Linking leaves the guide unchanged; " +
+        "unlink_folder_guide takes it out again. Delete a document or file with " +
+        "delete_folder_document or delete_folder_asset only when the person asked for it to go: " +
+        "neither can be undone. No tool deletes a whole folder; a person does that in the hub. " +
+        "list_folders with query finds folders and documents by their words, and with guide the " +
+        "folders a guide is in. rename_folder_document renames a document; " +
+        "get_folder_document_history reads earlier versions, so a bad edit can be put back.\n" +
         "A FOLLOW-UP IS MORE CONTEXT FOR A GUIDE, WRITTEN AS ITS OWN GUIDE. When a guide needs " +
         "more context — a missing detail, a step that needed explaining, what changed since, what " +
         "you found doing it — publish that context with publish_guide `parent` set to the guide's " +
@@ -526,12 +538,16 @@ export function buildServer() {
     {
       title: "List project folders",
       annotations: READS,
-      description: "Find project folders of documents, assets and guides. Requires sync sign-in.",
-      inputSchema: { scope: z.string().optional().describe('"all", "mine", or a team slug') },
+      description: `Find project folders of documents, assets and guides. Pass query to find the folders whose name, description, or any document's name or text mention those words; each then names its matching documents. Pass guide to find the folders a guide is in. Requires sync sign-in.`,
+      inputSchema: {
+        scope: z.string().optional().describe('"all", "mine", or a team slug'),
+        query: z.string().optional().describe("Words to look for in folders and their documents"),
+        guide: z.string().optional().describe("A guide id: only the folders it is linked in"),
+      },
     },
-    async ({ scope }) => {
+    async ({ scope, query, guide }) => {
       try {
-        return json(await api.folders(scope || "all"));
+        return json(await api.folders(scope || "all", { query, guide }));
       } catch (err) {
         return fail(err);
       }
@@ -543,16 +559,57 @@ export function buildServer() {
       title: "Create project folder",
       annotations: ADDS,
       description:
-        "Create a folder for project documents and assets after checking list_folders. Omit team for a private folder; pass a team slug only when sharing was requested.",
+        "Create a folder or nested subfolder after checking list_folders. Pass parent to nest it; omit team for a private root, and pass a team slug only when sharing was requested. A subfolder inherits its parent's space.",
       inputSchema: {
         title: z.string().describe("Name of the project or body of work"),
         description: z.string().optional().describe("Short purpose of the folder"),
         team: z.string().optional().describe("Team slug; omit for a private folder"),
+        parent: z
+          .string()
+          .optional()
+          .describe("Parent folder id for a nested subfolder; omit for a top-level folder"),
+        color: z
+          .enum(["coral", "amber", "green", "blue", "violet"])
+          .optional()
+          .describe("Optional grouping color"),
+      },
+    },
+    async ({ title, description, team, parent, color }) => {
+      try {
+        return json(
+          await api.createFolder(title, description || "", team || "", parent || "", color || ""),
+        );
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+  server.registerTool(
+    "update_folder",
+    {
+      title: "Organize project folder",
+      annotations: ADDS,
+      description:
+        "Rename, describe, recolor or move a folder. Pass parent as an empty string to move it to the top level. A folder cannot move inside itself or a descendant, or into another team/private space.",
+      inputSchema: {
+        folder: z.string(),
+        title: z.string().optional(),
+        description: z.string().optional(),
+        parent: z
+          .string()
+          .optional()
+          .describe("New parent folder id; empty string means top level"),
+        color: z.enum(["", "coral", "amber", "green", "blue", "violet"]).optional(),
       },
     },
-    async ({ title, description, team }) => {
+    async ({ folder, title, description, parent, color }) => {
       try {
-        return json(await api.createFolder(title, description || "", team || ""));
+        const changes = Object.fromEntries(
+          Object.entries({ title, description, parent, color }).filter(
+            ([, value]) => value !== undefined,
+          ),
+        );
+        return json(await api.updateFolder(folder, changes));
       } catch (err) {
         return fail(err);
       }
@@ -678,13 +735,51 @@ export function buildServer() {
       }
     },
   );
+  server.registerTool(
+    "rename_folder_document",
+    {
+      title: "Rename folder document",
+      annotations: ADDS,
+      description:
+        "Rename a folder document. Its id, text and history stay; no version is needed, because a rename cannot overwrite anyone's text.",
+      inputSchema: { folder: z.string(), document: z.string(), name: z.string() },
+    },
+    async ({ folder, document, name }) => {
+      try {
+        return json(await api.renameFolderDocument(folder, document, name));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+  server.registerTool(
+    "get_folder_document_history",
+    {
+      title: "Read folder document history",
+      annotations: READS,
+      description:
+        "Read a folder document's earlier versions. Without version, lists them newest first; with version, returns that version's text. To bring one back, save it with save_folder_document over the current version.",
+      inputSchema: {
+        folder: z.string(),
+        document: z.string(),
+        version: z.number().int().positive().optional(),
+      },
+    },
+    async ({ folder, document, version }) => {
+      try {
+        return json(await api.folderDocumentHistory(folder, document, version || 0));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
   server.registerTool(
     "link_folder_guide",
     {
       title: "Link guide to folder",
       annotations: ADDS,
       description:
-        "Put an existing task or handoff beside the folder documents and assets it uses.",
+        "Put a task, bug or handoff guide in the folder, beside the documents and assets it uses: one just published or one that already existed.",
       inputSchema: { folder: z.string(), guide: z.string() },
     },
     async ({ folder, guide }) => {
@@ -696,6 +791,60 @@ export function buildServer() {
     },
   );
 
+  server.registerTool(
+    "unlink_folder_guide",
+    {
+      title: "Unlink guide from folder",
+      annotations: ADDS,
+      description:
+        "Take a guide out of a folder. Only the link goes: the guide itself is unchanged, and link_folder_guide puts it back.",
+      inputSchema: { folder: z.string(), guide: z.string() },
+    },
+    async ({ folder, guide }) => {
+      try {
+        return json(await api.unlinkFolderGuide(folder, guide));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "delete_folder_document",
+    {
+      title: "Delete folder document",
+      annotations: REMOVES,
+      description:
+        "Delete one document from a folder, with its earlier versions. It cannot be brought back, so do it only when the person asked for that document to go; to change what it says, use save_folder_document instead.",
+      inputSchema: { folder: z.string(), document: z.string() },
+    },
+    async ({ folder, document }) => {
+      try {
+        return json(await api.deleteFolderDocument(folder, document));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "delete_folder_asset",
+    {
+      title: "Delete folder file",
+      annotations: REMOVES,
+      description:
+        "Delete one file from a folder. It cannot be brought back, so do it only when the person asked for that file to go.",
+      inputSchema: { folder: z.string(), asset: z.string() },
+    },
+    async ({ folder, asset }) => {
+      try {
+        return json(await api.deleteFolderAsset(folder, asset));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
   server.registerTool(
     "search_guides",
     {
@@ -769,8 +918,8 @@ export function buildServer() {
         "delivery of, and every verdict and ack they gave. Each item has a rendered `text` line " +
         "and the guide's repo. Use it to answer 'what have I been working on', to write a " +
         "standup or a weekly summary, or to find work from a repo by when it happened rather " +
-        "than by what it was called. This is the opposite of `activity`, which is what other " +
-        "people did. IMPORTANT: it records what was passed along, not what was worked on — work " +
+        "than by what it was called. The hub calls this page Activities, so 'my activities' means " +
+        "this tool. It is the opposite of `activity`, which is what other people did. IMPORTANT: it records what was passed along, not what was worked on — work " +
         "that never became a guide has no entry, so never present it as a complete record of " +
         "this user's work, and never infer that a quiet period was an idle one.",
       inputSchema: {
@@ -797,8 +946,9 @@ export function buildServer() {
       annotations: READS,
       description:
         "What has happened to this user's guides and handoffs: who pulled one, who archived one, " +
-        "who was handed what, who joined a team. Each item has a ready-made `text` line. This only " +
-        "reads; clear_activity is what marks the feed seen.",
+        "who was handed what, who joined a team. Each item has a ready-made `text` line. This is " +
+        "the hub's notifications, not its Activities page — for the user's own acts ('my " +
+        "activities'), use log. This only reads; clear_activity is what marks the feed seen.",
       inputSchema: {
         all: z.boolean().default(false).describe("include what the user has already seen"),
       },