passalong 0.15.1 → 0.16.0

package/bin/passalong

@@ -26,7 +26,8 @@
 //   passalong hub                 open your synced guides in the browser
 //   passalong take <id>           you are doing it — said before the work, so the sender stops guessing
 //   passalong pass <id> <why>     it is not yours — hands it back to its author with your reason
-//   passalong assign <id> <to>    give it to @handle, a #group, or "team" — yours, or assigned to you
+//   passalong assign <id> <to>    give it to @handle (or several: @ada @bola), a #group, or "team" — yours, or assigned to you
+//   passalong recall <id>         take back something you sent: private again, gone from their inboxes
 //   passalong admin create <email>   make an account that runs Passalong (owner only)
 //   passalong admin list          who runs it
 //   passalong admin grant|revoke <@handle>   make an existing account an admin, or stop it being one
@@ -50,6 +51,8 @@
 //   passalong team invite [email] make an invite link (mailed when an email is given)
 //   passalong team join <link|code>  accept an invite
 //   passalong team use <slug>     switch the current team
+//   passalong team promote|demote <@handle>  make a teammate an admin, or a member again
+//   passalong team remove <@handle>  take a teammate out; `team leave` leaves yourself
 //   passalong setup               install the Claude Code capture skill, MCP server and hooks
 //   passalong now                 what this worktree holds and what is waiting (the hooks call --hook)
 //   passalong mcp                 run the MCP server over stdio
@@ -666,12 +669,20 @@ const commands = {
 
   async assign(f) {
     const id = f._[0] || die('usage: passalong assign <id> <@handle | #group | team>');
-    const to = f._[1] || die('say who: @handle for one person, #group, or "team" for everyone');
+    const to = f._.slice(1).join(",") || die('say who: @handle (or several), #group, or "team" for everyone');
     const r = await passalong.assign(id, to).catch((e) => die(e.message));
     const back = r.taken_back ? ` — taken back from ${r.taken_back} who had it, and they were told` : "";
     console.error(`${r.id} is now for ${r.to || "everyone in the team"}${back}`);
   },
 
+  async recall(f) {
+    const id = f._[0] || die("usage: passalong recall <id>");
+    const r = await passalong.recall(id).catch((e) => die(e.message));
+    console.error(`${r.id} is private again, and gone from their inboxes`);
+    if (r.already_opened_by)
+      console.error(`${r.already_opened_by} ${r.already_opened_by === 1 ? "person" : "people"} had already opened it, and keep what they pulled`);
+  },
+
   // ---- who runs the product ---------------------------------------------------------------
   // `passalong admin <create|list|grant|revoke>`. An admin signs in like anybody else: the role is
   // a column, so there is no admin password and no admin token — only an account that has it.
@@ -901,7 +912,7 @@ const commands = {
       const t = await api.team(cfg.team).catch((e) => die(e.message));
       console.log(`${t.name} (${t.slug}) — ${t.members.length} member${t.members.length === 1 ? "" : "s"}, ${t.guides} guide${t.guides === 1 ? "" : "s"}`);
       for (const m of t.members)
-        console.log(`  ${m.handle ? `@${m.handle}` : "(no handle)"}${m.name ? `  ${m.name}` : ""}  ${m.role}  joined ${relDate(m.joined)}`);
+        console.log(`  ${m.handle ? `@${m.handle}` : "(no handle)"}${m.name ? `  ${m.name}` : ""}  ${m.role === "owner" ? "admin" : m.role}  joined ${relDate(m.joined)}`);
       return;
     }
     if (sub === "create") {
@@ -934,6 +945,22 @@ const commands = {
       if (who && !who.handle) console.error("teammates address you by handle: passalong me --handle <you>");
       return;
     }
+    if (sub === "promote" || sub === "demote") {
+      const slug = cfg.team || die("no current team — passalong team use <slug>");
+      const who = rest[0] || die(`usage: passalong team ${sub} <@handle>`);
+      const r = await api.setMemberRole(slug, who, sub === "promote" ? "admin" : "member").catch((e) => die(e.message));
+      console.error(`${who.startsWith("@") ? who : `@${who}`} is ${r.role === "admin" ? "an admin" : "a member"} of ${slug}${sub === "promote" ? " — they are told" : ""}`);
+      return;
+    }
+    if (sub === "remove" || sub === "leave") {
+      const slug = cfg.team || die("no current team — passalong team use <slug>");
+      const me = sub === "leave" ? (await api.me().catch((e) => die(e.message))).account : "";
+      const who = sub === "leave" ? me : rest[0] || die("usage: passalong team remove <@handle>");
+      const r = await api.removeMember(slug, who).catch((e) => die(e.message));
+      console.error(sub === "leave" ? `you left ${slug}` : `${who.startsWith("@") ? who : `@${who}`} is out of ${slug}${r.released ? `; ${r.released} hold${r.released === 1 ? "" : "s"} of theirs went back to waiting` : ""}`);
+      if (sub === "leave") api.setTeam("");
+      return;
+    }
     if (sub === "use") {
       const slug = rest[0] || die("usage: passalong team use <slug>");
       await api.team(slug).catch((e) => die(e.message));
@@ -941,7 +968,7 @@ const commands = {
       console.error(`current team: ${slug}`);
       return;
     }
-    die("usage: passalong team [create <name> | invite [email] | join <link> | use <slug>]");
+    die("usage: passalong team [create <name> | invite [email] | join <link> | use <slug> | promote <@handle> | demote <@handle> | remove <@handle> | leave]");
   },
 
   async setup() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.15.1",
+  "version": "0.16.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/skill/SKILL.md

@@ -14,7 +14,7 @@ session's history. Write for execution, not for permanence.
 **Check what is already open, and whether a guide is wanted at all.** Run `passalong now` (or
 `take` with no id over MCP) to see what this worktree holds and what was handed to you.
 
-- **The session answers something you hold** — hand it in (`passalong hand_in <id> …`) instead.
+- **The session answers something you hold** — use the MCP `hand_in` tool instead.
   Publishing a second guide about it leaves two records of one piece of work. Every hand-in carries
   what you ran and what came back — the command and the lines that decided it, a test summary, a
   link to the change, or a screenshot url. Copy each one out of the session as you go; at the end
@@ -44,7 +44,8 @@ machine, another agent session, or a teammate without your branch.
    what was decided and why, what finally worked, and how it was verified. Read the diff
    (`git diff`, `git log`) only to confirm details; the reasoning is in the transcript.
 3. **Write the guide** with the structure below. Be concrete: file paths, commands, exact error
-   strings, version numbers. Prefer a short guide with every section filled over a long one.
+   strings, version numbers. A transfer has no required body sections; keep only the context the
+   next agent needs.
 4. **Mark context-specific parts** so the receiver can adapt rather than copy. Put
    `ASSUMES: <thing>. If <alternative>, <what changes>.` at the start of any step that depends on
    this repo's stack, layout, or conventions.
@@ -60,14 +61,13 @@ machine, another agent session, or a teammate without your branch.
    who it was handed to) on stderr.
 
    **If what you are capturing is more context for an existing guide** — a missing detail, a step
-   that needed explaining, what changed since, what you found doing it — add `--follows <that id>`.
+   that needed explaining, or what changed since — add `--follows <that id>`.
    That publishes it as a follow-up: its own guide, listed under the original, and handed to
    whoever opens the original, person or agent. It travels the other way too — whoever opens the
    follow-up gets the guide it came out of, and where that guide has got to — so write it as a
-   note on that work rather than as a standalone brief. A session that started from a passalong guide
-   (`passalong start` or `pull` on an id, or an agent opened one) usually has context worth adding
-   this way. Whether the guide worked is still its own answer: `passalong works <id> <screenshot>` or
-   `passalong broken <id> <why>`.
+   note on that work rather than as a standalone brief. What you did or found while working on a
+   guide belongs in its `hand_in`, not a follow-up. Whether a guide worked is its own answer:
+   `passalong works <id> <screenshot>` or `passalong broken <id> <why>`.
 6. **Report** the id (and link if synced) and one line on how to use it on the other side:
    `passalong start <id>` in the target repo, or "start passalong <id>" to an agent with the
    Passalong MCP server. `start` rather than `pull` on purpose: it takes the handoff as well as
@@ -77,26 +77,25 @@ machine, another agent session, or a teammate without your branch.
 If the `passalong` command is missing, tell the user to run `npm i -g passalong && passalong setup` and
 still write the draft file so nothing is lost.
 
-## Two kinds of guide
+## Choose the right Passalong form
 
-`kind:` in the frontmatter says what a guide is for, and the receiver behaves differently for
-each. Absent means `transfer`, which is what every guide written before bug reports existed is.
+Every guide must state `kind:`. An absent kind is refused; the server never guesses one.
 
-| kind | what it is | what the receiver does |
-| --- | --- | --- |
-| `transfer` (or no `kind:` line) | finished work to repeat somewhere else | follows the **Steps** |
-| `bug` | a defect to fix where it is | fixes it — **Reproduce** shows the problem, it is not a procedure to apply |
+- `transfer` is context for a different repo, machine or agent session. It has no required
+  sections. Write only what the receiver needs to avoid starting cold.
+- `bug` is a defect to fix. Put the reproduction under `## Reproduce`, never `## Steps`, so the
+  receiver does not mistake the steps that show the defect for a remedy. Use `file_bugs` when
+  filing several independent defects.
+- `task` is work nobody has done yet. Use `plan_tasks` for a larger goal; its `## Acceptance`
+  gives the reviewer something to check. Do not write implementation steps for the taker.
 
-To file bugs you found but are not fixing, call `file_bugs` with all of them in one call — it
-opens a report and publishes each issue as its own guide, so any one of them can be handed to
-whoever fixes it. `publish_guide` is for a single guide: work you finished and want repeated, or
-one bug on its own.
-
-A bug has no `## Steps` and publishing one with a Steps section is refused. That is the whole
-reason the kinds are separate: "follow its Steps" is what the MCP server tells every agent that
-pulls a guide, and steps that reproduce a defect are the one list that must never be run as a
-remedy — an agent that follows them reproduces the bug, checks the Verification, finds it false
-because the bug is real, and reports that the guide does not work.
+**A project folder is not a guide.** When asked to keep a script, brief, screenshots or other
+assets together for continuing work, call `list_folders` first. Reuse a fitting folder, or call
+`create_folder` with a title and short description drawn from the person's request. Create the
+first Markdown document with `create_folder_document`; do not leave an empty folder or ask the
+person to fill a form. Omit `team` unless they asked to share it. Read a document and its version
+before `save_folder_document`; reread after a stale-version refusal. Add files with
+`add_folder_asset` and link an existing guide with `link_folder_guide` only when it uses the folder.
 
 ## Say it to a person
 
@@ -116,6 +115,7 @@ billing.ts per the Paystack spec, see PR 412."
 ---
 title: <what this accomplishes, as a verb phrase: "Add Paystack webhook verification">
 summary: <one or two plain sentences for a PERSON, 400 characters at most, no ids or paths: what this is and whether anyone has to act>
+kind: transfer
 author: <git user.name, if known>
 source_context: <repo or product this came from>
 status: published
@@ -123,26 +123,19 @@ stack_assumptions: [<runtime/framework/db/service versions the steps depend on>]
 tags: [<3 to 6 lowercase keywords>]
 ---
 
-## Problem
-What was broken or needed. Two or three sentences. Include the observable symptom.
-
-## Solution shape
-The approach at a high level, before any code. One short paragraph.
-
-## Decisions and rationale
-- **Chose X over Y** because Z. (Each real decision, with what was rejected.)
+## What changed
+The information the receiving agent needs, in the shape that makes it easiest to use.
 
-## Steps
-1. ASSUMES: <stack>. If <other>, <adjust>. Then the concrete step, with the file path and the code or command.
-2. ...
+## Why
+Decisions or constraints the receiver could not infer from the final code.
 
-## Verification
-Commands to run and what they should print. Test cases. What "done" looks like.
-
-## Gotchas
-- What failed along the way, the exact error, and why. What looked right but wasn't.
+## How to check
+Commands and expected results, if the receiver needs to repeat or verify the work.
 ```
 
+Those headings are examples, not a required template. A short transfer may be a paragraph.
+Include paths, assumptions, verification or gotchas only when they help the next agent act.
+
 ## Bug structure
 
 ```markdown
@@ -174,16 +167,15 @@ The behaviour that should have happened, as something the fixer can check.
 
 ## Quality bar
 
-- **Gotchas is the highest-value section.** If nothing went wrong, say what would have gone
-  wrong without a specific decision. Never leave it empty.
-- **Verification must be runnable.** A command and an expected output, not "make sure it works".
-- **Every ASSUMES has an alternative.** The point is adaptation on the other side.
+- **Write for the crossing.** State what another agent cannot learn from the destination repo.
+- **Verification, when relevant, must be checkable.** Give the command and expected result.
+- **State assumptions where they matter.** Say how the next environment may differ.
 - **One problem per guide.** A lesson from the same session that is not part of this fix goes in
-  its own guide (write and share it separately), not in this one's Gotchas.
+  its own guide only when it is separate work worth handing over.
 - **No session narration.** "First I looked at..." is noise. State the finding.
 - **No secrets.** Redact tokens, keys, and internal hostnames that would not apply elsewhere.
-- Title, Problem, and Steps are required; the guide will not publish without them.
-- For a bug: title, Problem and **Reproduce**. Never a Steps section — see the two kinds above.
+- Every guide needs a title, summary and explicit kind. A transfer needs no fixed body section.
+- A bug needs Problem and Reproduce. Never give a bug a Steps section.
 - The line above Problem is written by `file_bugs` and the hub's form. It is in the document, not
   added by whatever served it, so an agent that fetched the share link over plain HTTP — with no
   MCP server and no knowledge of Passalong — still reads what the document is before acting on it.

package/src/api.js

@@ -1,6 +1,8 @@
 // Client for the hosted sync API (apps/api). Everything here is optional: with no token the
 // CLI is a purely local tool, and every function throws an ApiError the CLI turns into a hint.
 import { readFileSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { basename } from "node:path";
 import { nameFor, readAccounts, readConfig, saveTeam } from "./store.js";
 
 /**
@@ -145,7 +147,10 @@ export async function meWith(tokenValue, base = baseUrl()) {
 
 export { nameFor };
 
-async function call(path, { method = "GET", body, auth = true, raw = false } = {}) {
+async function call(
+  path,
+  { method = "GET", body, auth = true, raw = false, uploadName = "" } = {},
+) {
   const headers = { ...CLIENT };
   if (auth) {
     if (needsChoice()) throw new ApiError(409, choiceMessage());
@@ -154,14 +159,24 @@ async function call(path, { method = "GET", body, auth = true, raw = false } = {
     headers.authorization = `Bearer ${t}`;
   }
   if (body !== undefined) {
-    headers["content-type"] = typeof body === "string" ? "text/markdown" : "application/json";
+    headers["content-type"] = uploadName
+      ? "application/octet-stream"
+      : typeof body === "string"
+        ? "text/markdown"
+        : "application/json";
   }
+  if (uploadName) headers["x-file-name"] = uploadName.replace(/[^\x20-\x7e]/g, "").slice(0, 120);
   let res;
   try {
     res = await fetch(`${baseUrl()}${path}`, {
       method,
       headers,
-      body: body === undefined ? undefined : typeof body === "string" ? body : JSON.stringify(body),
+      body:
+        body === undefined
+          ? undefined
+          : uploadName || typeof body === "string"
+            ? body
+            : JSON.stringify(body),
     });
   } catch (err) {
     throw new ApiError(0, `could not reach ${baseUrl()} (${err.message})`);
@@ -273,10 +288,49 @@ export const team = (slug) => call(`/v1/teams/${encodeURIComponent(slug)}`);
 export const createTeam = (name) => call("/v1/teams", { method: "POST", body: { name } });
 export const invite = (slug, email = "") =>
   call(`/v1/teams/${encodeURIComponent(slug)}/invites`, { method: "POST", body: { email } });
+export const setMemberRole = (slug, who, role) =>
+  call(`/v1/teams/${encodeURIComponent(slug)}/members/${encodeURIComponent(who)}`, {
+    method: "PATCH",
+    body: { role },
+  });
+export const removeMember = (slug, who) =>
+  call(`/v1/teams/${encodeURIComponent(slug)}/members/${encodeURIComponent(who)}`, {
+    method: "DELETE",
+  });
 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 folder = (id) => call(`/v1/folders/${encodeURIComponent(id)}`);
+export const folderDocument = (folderId, documentId) =>
+  call(`/v1/folders/${encodeURIComponent(folderId)}/documents/${encodeURIComponent(documentId)}`);
+export const folderAsset = (folderId, assetId) =>
+  call(`/v1/folders/${encodeURIComponent(folderId)}/assets/${encodeURIComponent(assetId)}/agent`);
+export async function addFolderAsset(folderId, path, name = "") {
+  const file = await stat(path);
+  if (!file.isFile()) throw new ApiError(400, "Choose a file to add to the folder.");
+  if (file.size > 10 * 1024 * 1024) throw new ApiError(413, "That file is over 10 MB.");
+  return call(`/v1/folders/${encodeURIComponent(folderId)}/assets`, {
+    method: "POST",
+    body: new Uint8Array(await readFile(path)),
+    uploadName: name || basename(path),
+  });
+}
+export const createFolderDocument = (folderId, name, body) =>
+  call(`/v1/folders/${encodeURIComponent(folderId)}/documents`, {
+    method: "POST",
+    body: { name, body },
+  });
+export const saveFolderDocument = (folderId, documentId, version, body) =>
+  call(`/v1/folders/${encodeURIComponent(folderId)}/documents/${encodeURIComponent(documentId)}`, {
+    method: "PUT",
+    body: { version, body },
+  });
+export const linkFolderGuide = (folderId, guide) =>
+  call(`/v1/folders/${encodeURIComponent(folderId)}/guides`, { method: "POST", body: { guide } });
 /** 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 || "" })}`);
@@ -347,6 +401,8 @@ export const release = (id) =>
 /** The four verbs every guide answers to. See docs/V2.md §11. */
 export const working = () => call("/v1/working");
 export const handedIn = () => call("/v1/handed_in");
+export const recall = (id) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/recall`, { method: "POST", body: {} });
 export const assign = (id, to) =>
   call(`/v1/guides/${encodeURIComponent(id)}/assign`, { method: "POST", body: { to } });
 export const take = (body) => call("/v1/take", { method: "POST", body });

package/src/mcp.js

@@ -298,7 +298,8 @@ export function buildServer() {
         "is a spelling that is not one of the three. " +
         `kind: task is work nobody has done yet. Sections: ${TASK_SECTIONS.join(", ")}. ` +
         "It has no Steps: work out how to reach Goal within Constraints, leave Out of scope " +
-        "alone, and treat Acceptance as the definition of done. hand_in with `markdown`: a " +
+        "alone, and treat Acceptance as the definition of done. New tasks say `status: draft`; " +
+        "a proposal awaiting a team decision stays Draft until a person makes it Ready. hand_in with `markdown`: a " +
         "transfer guide about what you did (guide_template kind transfer shows the shape) — its " +
         "author reviews it against Acceptance.\n" +
         `kind: transfer (or no kind: line) is a finished implementation to repeat here. Sections: ${SECTIONS.join(", ")}. ` +
@@ -343,6 +344,19 @@ export function buildServer() {
         "the user asks what they have been working on, or wants a standup or a summary of a " +
         "period, call log — but say that it holds what they passed along and not everything they " +
         "did. Gotchas are the highest-value section: record what failed and why.\n" +
+        "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. " +
+        "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 " +
+        "or one returned by list_folders, and omit it for a private folder. Use the returned " +
+        "folder id with create_folder_document to add Markdown, get_folder to see its contents, " +
+        "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" +
         "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 " +
@@ -490,7 +504,7 @@ export function buildServer() {
       annotations: ADDS,
       description:
         "Reassign a guide or task the user wrote, or one assigned to them, to someone else in its team, when the user asks: " +
-        '`to` is @handle for one person, #group for the people who do a thing, or "team" for ' +
+        '`to` is @handle for one person, "@ada,@bola" for several named people, #group for the people who do a thing, or "team" for ' +
         "everyone. Whoever held it and is left out has it taken back and is told; a task then only " +
         "goes to the new assignee's agents. Its author, or whoever it is assigned to, can do this.",
       inputSchema: {
@@ -507,6 +521,181 @@ export function buildServer() {
     },
   );
 
+  server.registerTool(
+    "list_folders",
+    {
+      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') },
+    },
+    async ({ scope }) => {
+      try {
+        return json(await api.folders(scope || "all"));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+  server.registerTool(
+    "create_folder",
+    {
+      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.",
+      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"),
+      },
+    },
+    async ({ title, description, team }) => {
+      try {
+        return json(await api.createFolder(title, description || "", team || ""));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+  server.registerTool(
+    "get_folder",
+    {
+      title: "Open project folder",
+      annotations: READS,
+      description: "List a folder's documents, assets and linked guides.",
+      inputSchema: { folder: z.string() },
+    },
+    async ({ folder }) => {
+      try {
+        return json(await api.folder(folder));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+  server.registerTool(
+    "get_folder_document",
+    {
+      title: "Read folder document",
+      annotations: READS,
+      description: "Read the full Markdown and version before editing it.",
+      inputSchema: { folder: z.string(), document: z.string() },
+    },
+    async ({ folder, document }) => {
+      try {
+        return json(await api.folderDocument(folder, document));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+  server.registerTool(
+    "get_folder_asset",
+    {
+      title: "Read folder asset",
+      annotations: READS,
+      description:
+        "Read an image or small text file from a folder into this agent's context. Other file types stay private downloads.",
+      inputSchema: { folder: z.string(), asset: z.string() },
+    },
+    async ({ folder, asset }) => {
+      try {
+        const file = await api.folderAsset(folder, asset);
+        const { data, text: body, ...meta } = file;
+        return {
+          content: data
+            ? [
+                { type: "text", text: file.name },
+                { type: "image", data, mimeType: file.type },
+              ]
+            : [{ type: "text", text: `${file.name}\n\n${body || ""}` }],
+          structuredContent: meta,
+        };
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "add_folder_asset",
+    {
+      title: "Add file to project folder",
+      annotations: { ...ADDS, openWorldHint: true },
+      description:
+        "Add a screenshot, reference file or other asset from this machine to a folder. Use a real file path you can read; the bytes are uploaded directly, not copied into a guide. Images, PDF, ZIP and text are accepted up to 10 MB.",
+      inputSchema: {
+        folder: z.string().describe("folder id returned by create_folder or list_folders"),
+        file: z.string().describe("path to the file on this machine"),
+        name: z.string().optional().describe("label in the folder; defaults to the filename"),
+      },
+    },
+    async ({ folder, file, name }) => {
+      try {
+        return json(await api.addFolderAsset(folder, file, name || ""));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "create_folder_document",
+    {
+      title: "Write new folder document",
+      annotations: ADDS,
+      description: "Add Markdown such as a brief or script to a folder.",
+      inputSchema: { folder: z.string(), name: z.string(), body: z.string() },
+    },
+    async ({ folder, name, body }) => {
+      try {
+        return json(await api.createFolderDocument(folder, name, body));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+  server.registerTool(
+    "save_folder_document",
+    {
+      title: "Save folder document",
+      annotations: ADDS,
+      description:
+        "Save a new revision. Send the version returned when you read it; a newer edit is refused.",
+      inputSchema: {
+        folder: z.string(),
+        document: z.string(),
+        version: z.number().int().positive(),
+        body: z.string(),
+      },
+    },
+    async ({ folder, document, version, body }) => {
+      try {
+        return json(await api.saveFolderDocument(folder, document, version, body));
+      } 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.",
+      inputSchema: { folder: z.string(), guide: z.string() },
+    },
+    async ({ folder, guide }) => {
+      try {
+        return json(await api.linkFolderGuide(folder, guide));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
   server.registerTool(
     "search_guides",
     {
@@ -1160,7 +1349,9 @@ export function buildServer() {
         to: z
           .string()
           .optional()
-          .describe("team slug, team/@handle for one teammate, or team/#group for a set of them"),
+          .describe(
+            "team slug, team/@handle for one teammate, team/@ada,@bola for several named teammates, or team/#group for a set of them",
+          ),
         cwd: z
           .string()
           .optional()
@@ -1233,7 +1424,9 @@ export function buildServer() {
         to: z
           .string()
           .optional()
-          .describe("team slug, team/@handle for one teammate, or team/#group for a set of them"),
+          .describe(
+            "team slug, team/@handle for one teammate, team/@ada,@bola for several named teammates, or team/#group for a set of them",
+          ),
         issues: z
           .array(
             z.object({

package/src/passalong.js

@@ -523,6 +523,19 @@ export async function assign(ref, to) {
   return r;
 }
 
+/**
+ * Take back something you sent: it is private again and gone from every inbox it was in. Refused
+ * while somebody is on it. Whoever already opened it keeps what they pulled. The local copy is
+ * dropped so the next read shows it without the address.
+ */
+export async function recall(ref) {
+  needsSync("taking a guide back");
+  const id = await resolveId(ref);
+  const r = await api.recall(id);
+  store.remove(id);
+  return r;
+}
+
 /** Not this agent's to do: what it held is open again, and `why` goes to whoever is next. */
 export async function pass(id, why, { cwd = process.cwd() } = {}) {
   needsSync("passing work");