passalong 0.6.0 → 0.9.0

package/src/mcp.js

@@ -8,6 +8,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import * as api from "./api.js";
+import { refusal, runChecks } from "./checks.js";
 import { AREAS, BUG_SECTIONS, parse, SECTIONS, TASK_SECTIONS, template } from "./guide.js";
 import * as passalong from "./passalong.js";
 
@@ -23,6 +24,16 @@ const VERSION = JSON.parse(
 
 const text = (s) => ({ content: [{ type: "text", text: s }] });
 
+/**
+ * Said in front of every guide an agent opens, whatever its kind: the hand-in needs evidence, and
+ * evidence is collected while the work happens, not reconstructed from memory once it is done.
+ * Mirrors KEEP_EVIDENCE in apps/api/src/mcp-http.ts.
+ */
+const KEEP_EVIDENCE =
+  "KEEP YOUR EVIDENCE AS YOU GO. hand_in needs it: the commands you ran and what came back, the " +
+  "test summary, the link to the change. Copy each one when it happens — at the end you will be " +
+  "writing from memory, which is the thing evidence is here to replace.\n\n";
+
 /**
  * What to say in front of a guide whose kind changes what the reader should do with it.
  *
@@ -36,7 +47,8 @@ function leadFor(meta) {
     return (
       "THIS IS A BUG REPORT, NOT WORK TO REPEAT. Do not follow Reproduce as instructions " +
       "— those steps produce the defect. Fix what Problem describes, then check " +
-      "Verification and answer with hand_in.\n\n"
+      "Verification and answer with hand_in.\n\n" +
+      KEEP_EVIDENCE
     );
   if (meta.kind === "task")
     return (
@@ -44,8 +56,12 @@ function leadFor(meta) {
       "reach Goal within Constraints, and leave Out of scope alone. It is done when every check " +
       "under Acceptance holds. Opening it here does not make it yours: to work on it, call take " +
       "with its id in the repo it is for, so no other agent can. Then progress, and hand_in " +
-      "with a write-up.\n\n"
+      "with a write-up.\n\n" +
+      KEEP_EVIDENCE
     );
+  // A transfer guide is handed over untouched: it is a document to follow, and anything in front
+  // of it is one more thing that is not the document. The reminder still reaches the agent on the
+  // answer's `next` line, which is where every other instruction from the server rides.
   return "";
 }
 
@@ -78,7 +94,65 @@ async function related(meta) {
     return "";
   }
 }
-const json = (data) => text(JSON.stringify(data, null, 2));
+/**
+ * An answer a client can read as data as well as prose.
+ *
+ * `structuredContent` is the same JSON the text block holds; the spec asks for both, because a
+ * tool "that returns structured content SHOULD also return the serialized JSON in a TextContent
+ * block" for clients that only read text. Only an object goes in the structured field — the spec
+ * allows any JSON value there, but a bare array or string tells a client nothing it could key on.
+ */
+const json = (data) => ({
+  ...text(JSON.stringify(data, null, 2)),
+  ...(data && typeof data === "object" && !Array.isArray(data) ? { structuredContent: data } : {}),
+});
+
+/**
+ * What each tool does to the world, said out loud. Mirrors the same block in
+ * apps/api/src/mcp-http.ts, which had these and this server did not — the same four jobs described
+ * to a client two different ways, on the surface most agents actually reach.
+ *
+ * MCP's defaults for a tool that says nothing are the worst case — it writes, it may destroy, it
+ * reaches outside — and a client acts on them: over HTTP, ChatGPT badged every tool here, `inbox`
+ * included, as a destructive public write. The spec is equally clear that these are hints and
+ * nothing more: "clients MUST consider tool annotations to be untrusted unless they come from
+ * trusted servers". They are a description, not a permission.
+ *
+ * `openWorldHint` is false for everything that stays inside Passalong. Only attach_screenshot
+ * reaches outside it, for a file on this machine that Passalong did not put there.
+ */
+/**
+ * What the three verbs that answer with JSON return. Declared only for those: `outputSchema` puts
+ * the obligation on the server — "Servers MUST provide structured results that conform to this
+ * schema", while a client only SHOULD check — so it is a promise, and promising a shape this
+ * server does not control would be worse than staying quiet. `take` is the reason for the rule
+ * rather than an exception to it: it answers with the guide's markdown and a lead-in to read, not
+ * with a record.
+ *
+ * Every field is optional and the objects are open. The four calls serve three kinds of guide and
+ * the routes add fields freely, so a required key here would be a promise broken by a kind that
+ * does not carry it.
+ */
+// The object itself is handed to registerTool, not its `.shape`: a shape is rebuilt into a closed
+// object and advertised as `additionalProperties: false`, which would be this server promising that
+// an answer carries nothing else — and then breaking that promise the first time a route adds a
+// field. Passing the object through keeps it open.
+const openObject = (shape) => z.object(shape).partial().passthrough();
+const progressOut = openObject({
+  id: z.string(),
+  lease_until: z.string(),
+  note: z.string(),
+});
+const handInOut = openObject({
+  id: z.string(),
+  state: z.string(),
+  report: z.string(),
+  ok: z.boolean(),
+});
+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 };
 const fail = (err) => ({ content: [{ type: "text", text: err.message }], isError: true });
 
 /**
@@ -87,7 +161,11 @@ const fail = (err) => ({ content: [{ type: "text", text: err.message }], isError
  */
 export function nextNote({ next = [], say = "" } = {}, id = "") {
   const lines = next.map(
-    (s) => `  ${s.tool}${id && s.tool !== "take" ? ` ${id}` : ""} — when ${s.when} (${s.why})`,
+    (s) =>
+      `  ${s.tool}${id && s.tool !== "take" ? ` ${id}` : ""} — when ${s.when} (${s.why})` +
+      // What the call has to carry, under the call it belongs to: an agent that reads this at the
+      // end of a long session should not have to remember hand_in takes evidence.
+      (s.with ? `\n      with ${s.with}` : ""),
   );
   if (say) lines.unshift(`  ${say}`);
   return lines.length ? `<!-- passalong: next:\n${lines.join("\n")}\n-->` : "";
@@ -102,7 +180,12 @@ const failWith = (err) => {
   };
 };
 
-export async function serve() {
+/**
+ * The server, built but not connected. Split out so the tool surface can be read without a
+ * transport — `test/mcp-surface.test.js` lists the tools over an in-memory pair and checks what
+ * each one says about itself. apps/api/src/mcp-http.ts is shaped the same way.
+ */
+export function buildServer() {
   const server = new McpServer(
     { name: "passalong", version: VERSION },
     {
@@ -118,6 +201,11 @@ export async function serve() {
         "stop, stop. OPEN A GUIDE YOU MEAN TO ACT ON WITH take, NOT get_guide: get_guide only " +
         "reads, and the sender learns nothing. If take says somebody else has it, tell the user " +
         "instead of doing the work twice.\n" +
+        "EVERY HAND-IN CARRIES EVIDENCE: 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. " +
+        "Collect it as you work rather than writing it from memory at the end. hand_in without " +
+        "it is refused, because the write-up and the verdict are both your word for your own " +
+        "work and evidence is the part the person reviewing it can check.\n" +
         `kind: task (the default) 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 " +
@@ -150,6 +238,16 @@ export async function serve() {
         "session into a guide (guide_template kind transfer shows the shape) and call " +
         "publish_guide, with `to` as team, team/@handle for one teammate, or team/#group for the " +
         "people who do a thing. " +
+        "BEFORE PUBLISHING ANYTHING, CHECK WHAT IS ALREADY OPEN: call take with no id, or read the " +
+        "inbox, and see what you hold. If this session's work answers something you hold, hand_in " +
+        "that — never publish a second guide about it. A transfer guide is for work that has to " +
+        "cross a boundary: another repo, another machine, a teammate without your branch. Work you " +
+        "committed and pushed where the team can already see it has crossed no boundary, and a " +
+        "guide about it is one more thing for somebody to read and review; what is worth " +
+        "publishing from a session like that is what is still open, as a bug or a task. " +
+        '"Update the passalong", "add this to passalong" and the like are ambiguous — hand in ' +
+        "what you hold, add a follow-up, or publish something new? Ask which, in one line, rather " +
+        "than publishing and leaving the user to undo it. " +
         "At the start of work, inbox shows guides teammates have handed to this user — take one " +
         "to start it — and activity shows whether the guides they handed off have landed. When " +
         "the user asks what they have been working on, or wants a standup or a summary of a " +
@@ -160,7 +258,9 @@ export async function serve() {
         "you found doing it — publish that context with publish_guide `parent` set to the guide's " +
         "id. It is listed under the original, and anyone who opens the original, person or agent, " +
         "gets it too. get_guide and take return a guide's follow-ups after it; read them " +
-        "before acting.",
+        "before acting. They also return the guide it follows, in front of it: a follow-up is a " +
+        "note on a bigger piece of work, not the work. If it needs that guide done and it is " +
+        "not, say so rather than starting.",
     },
   );
 
@@ -172,7 +272,12 @@ export async function serve() {
   const answer = (r, id) => {
     const { next, say, ...rest } = r || {};
     const note = nextNote({ next, say }, id);
-    return text(`${JSON.stringify(rest, null, 2)}${note ? `\n${note}` : ""}`);
+    // The note is what the agent acts on and it is prose, so it stays in the text half only. The
+    // structured half is the answer itself, which is what `outputSchema` below describes.
+    return {
+      ...text(`${JSON.stringify(rest, null, 2)}${note ? `\n${note}` : ""}`),
+      structuredContent: rest,
+    };
   };
 
   async function doTake({ id, cwd, any }) {
@@ -192,12 +297,13 @@ export async function serve() {
       const meta = parse(r.guide.markdown).meta;
       const siblings = await related(meta);
       const context = await passalong.followUps(meta);
+      const from = await passalong.parentGuide(meta);
       const held =
         `<!-- passalong: ${r.guide.id} is yours` +
         `${r.guide.resumed ? " (you already held it — carry on from where it was left)" : ""}; ` +
         `written to ${r.path}. -->`;
       return text(
-        `${leadFor(meta)}${r.guide.markdown}${siblings}${context ? `\n\n${context}` : ""}` +
+        `${from}${leadFor(meta)}${r.guide.markdown}${siblings}${context ? `\n\n${context}` : ""}` +
           `\n\n${held}\n${nextNote(r, r.guide.id)}\n${passalong.followUpNote(meta)}`,
       );
     } catch (err) {
@@ -220,15 +326,31 @@ export async function serve() {
     }
   }
 
-  async function doHandIn({ id, ok, note, markdown, report, pr, cwd }) {
+  async function doHandIn({ id, ok, note, evidence, checks, writeup, markdown, report, pr, cwd }) {
     try {
+      // A check that names a command is run here, before anything is recorded, and its exit code
+      // decides it rather than the agent's account of it. A failure is refused with the command's
+      // own output: the claim is still held, nothing is written, and the agent has what it needs
+      // to fix. Checks with no `cmd` pass straight through to the prose rule.
+      const at = cwd || process.cwd();
+      const done = runChecks(checks || [], { cwd: at });
+      if (done.failed)
+        return {
+          content: [
+            { type: "text", text: refusal(done.failed, { ran: done.ran, total: checks.length }) },
+          ],
+          isError: true,
+        };
       const r = await passalong.handIn(id, {
         ok,
         note: note || "",
+        evidence: evidence || "",
+        checks: done.checks,
+        writeup: writeup || "",
         markdown,
         report,
         pr: pr || "",
-        cwd: cwd || process.cwd(),
+        cwd: at,
       });
       return answer(r, id);
     } catch (err) {
@@ -244,10 +366,35 @@ export async function serve() {
     }
   }
 
+  server.registerTool(
+    "assign",
+    {
+      title: "Give it to someone else",
+      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 ' +
+        "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: {
+        id: z.string().describe("passalong id"),
+        to: z.string().describe('"@handle", "#group", or "team"'),
+      },
+    },
+    async ({ id, to }) => {
+      try {
+        return json(await passalong.assign(id, to));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
   server.registerTool(
     "search_guides",
     {
       title: "Search guides",
+      annotations: READS,
       description:
         "Search transfer guides by words in the title, tags, stack, or body: the user's own " +
         "(local and synced) plus every team they belong to. Empty query lists everything, newest first.",
@@ -270,6 +417,7 @@ export async function serve() {
     "inbox",
     {
       title: "Inbox",
+      annotations: READS,
       description:
         "Guides handed to this user (or to their teams) that they have not pulled yet. Call it " +
         "when starting work so handoffs are not missed. Needs sync (passalong login).",
@@ -288,6 +436,7 @@ export async function serve() {
     "board",
     {
       title: "Board",
+      annotations: READS,
       description:
         "The state of this user's transfers as queues: waiting on you (handed to you, not " +
         "pulled), not working (someone gave it a failing verdict — the most urgent), in flight " +
@@ -308,6 +457,7 @@ export async function serve() {
     "log",
     {
       title: "What this user did",
+      annotations: READS,
       description:
         "This user's own acts on guides, newest first: what they published, what they took " +
         "delivery of, and every verdict and ack they gave. Each item has a rendered `text` line " +
@@ -334,91 +484,62 @@ export async function serve() {
     },
   );
 
-  server.registerTool(
-    "ack_guide",
-    {
-      title: "Take it or pass it (same as take / pass)",
-      description:
-        "Kept for older prompts: taken=true is take with this id, taken=false is pass with `note` " +
-        "as the reason.",
-      inputSchema: {
-        id: z.string().describe("passalong id"),
-        taken: z.boolean().describe("true if you are doing it; false hands it back"),
-        note: z.string().default("").describe("why it is not yours (required when taken is false)"),
-        cwd: z
-          .string()
-          .optional()
-          .describe("the worktree you are working in; default is the server's cwd"),
-      },
-    },
-    async ({ id, taken, note, cwd }) =>
-      taken ? doTake({ id, cwd }) : doPass({ id, why: note || "", cwd }),
-  );
-
-  server.registerTool(
-    "verify_guide",
-    {
-      title: "Report whether it works (same as hand_in)",
-      description: "Kept for older prompts: exactly hand_in with `ok` and `note`.",
-      inputSchema: {
-        id: z.string().describe("passalong id"),
-        ok: z.boolean().describe("true if the Verification steps passed"),
-        note: z.string().default("").describe("what went wrong (required when ok is false)"),
-        cwd: z
-          .string()
-          .optional()
-          .describe("the worktree you are working in; default is the server's cwd"),
-      },
-    },
-    async (args) => doHandIn(args),
-  );
-
   server.registerTool(
     "activity",
     {
       title: "Activity",
+      annotations: READS,
       description:
-        "What has happened to this user's guides and handoffs: who pulled one, who marked one " +
-        "consumed, who was handed what, who joined a team. Each item has a ready-made `text` " +
-        "line. Read-only by default — it does not clear the user's unread feed unless asked.",
+        "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.",
       inputSchema: {
         all: z.boolean().default(false).describe("include what the user has already seen"),
-        mark_read: z.boolean().default(false).describe("clear the unread feed after reading"),
       },
     },
-    async ({ all, mark_read }) => {
+    async ({ all }) => {
       try {
-        const res = await passalong.activity({ all });
-        if (mark_read && res.unread) await passalong.seen();
-        return json(res);
+        return json(await passalong.activity({ all }));
       } catch (err) {
         return fail(err);
       }
     },
   );
 
+  /**
+   * Split out of `activity`, which took `mark_read` and so read on one call and wrote on the next.
+   *
+   * An annotation cannot say "sometimes": `readOnlyHint` was false for a tool that almost always
+   * only reads, which is a client being told the cautious lie on every call rather than the truth
+   * on the one that matters. Two tools, each true about itself.
+   */
   server.registerTool(
-    "start_guide",
+    "clear_activity",
     {
-      title: "Start work on a guide (same as take with an id)",
+      title: "Mark activity seen",
+      annotations: ADDS,
       description:
-        "Kept for older prompts: exactly take with this id — say you are doing it and get it in " +
-        "one call. Use it the moment you are going to do the work.",
-      inputSchema: {
-        ref: z.string().describe("passalong id (e.g. k3mq2xa7) or share URL"),
-        cwd: z
-          .string()
-          .optional()
-          .describe("the worktree you are working in; default is the server's cwd"),
-      },
+        "Clear the user's unread feed, after they have been shown what is in it. Read it with " +
+        "activity first — clearing what nobody was told about loses it.",
+      inputSchema: {},
+    },
+    async () => {
+      try {
+        const res = await passalong.activity({ all: false });
+        if (!res.unread) return json({ cleared: 0, unread: 0 });
+        await passalong.seen();
+        return json({ cleared: res.unread, unread: 0 });
+      } catch (err) {
+        return fail(err);
+      }
     },
-    async ({ ref, cwd }) => doTake({ id: ref, cwd }),
   );
 
   server.registerTool(
     "plan_tasks",
     {
       title: "Plan a goal as tasks",
+      annotations: ADDS,
       description:
         "Write tasks for agents: one step for a single task, or a larger goal broken into steps " +
         "an agent can each finish and a person can each check, written as drafts in order. The " +
@@ -462,68 +583,11 @@ export async function serve() {
     },
   );
 
-  server.registerTool(
-    "next_task",
-    {
-      title: "Take the next task (same as take with no id)",
-      description:
-        "Kept for older prompts: exactly take with no id. Takes the next guide waiting for this " +
-        "worktree's agent, or gives back the one it already holds.",
-      inputSchema: {
-        cwd: z
-          .string()
-          .optional()
-          .describe("the worktree you are working in; default is the server's cwd"),
-        any: z
-          .boolean()
-          .optional()
-          .describe("any repo, or none — only when the user asks for that"),
-      },
-    },
-    async ({ cwd, any }) => doTake({ cwd, any }),
-  );
-
-  server.registerTool(
-    "task_progress",
-    {
-      title: "Report progress (same as progress)",
-      description: "Kept for older prompts: exactly progress.",
-      inputSchema: {
-        id: z.string().describe("the id of what you hold"),
-        note: z.string().optional().describe("one line"),
-        cwd: z
-          .string()
-          .optional()
-          .describe("the worktree you are working in; default is the server's cwd"),
-      },
-    },
-    async (args) => doProgress(args),
-  );
-
-  server.registerTool(
-    "finish_task",
-    {
-      title: "Finish a task (same as hand_in)",
-      description: "Kept for older prompts: exactly hand_in, for a task.",
-      inputSchema: {
-        id: z.string().describe("the task's id"),
-        markdown: z.string().optional().describe("the transfer guide about this work"),
-        report: z.string().optional().describe("instead of markdown: id of one already published"),
-        pr: z.string().optional().describe("PR or branch link, when there is one"),
-        note: z.string().optional().describe("one line for the hub"),
-        cwd: z
-          .string()
-          .optional()
-          .describe("the worktree you are working in; default is the server's cwd"),
-      },
-    },
-    async (args) => doHandIn(args),
-  );
-
   server.registerTool(
     "take",
     {
       title: "Take work",
+      annotations: ADDS,
       description:
         "Say you are doing it, and get it. With `id`, that guide — any kind: a task, a bug, a " +
         "handoff. With no id, the next thing waiting for this worktree's agent. While you hold it " +
@@ -553,6 +617,8 @@ export async function serve() {
     "progress",
     {
       title: "Report progress",
+      outputSchema: progressOut,
+      annotations: ADDS,
       description:
         "Say you are still on what you hold, with a one-line note the hub shows. 30 minutes " +
         "without one marks it stalled. If the answer says you no longer hold it, stop.",
@@ -572,16 +638,74 @@ export async function serve() {
     "hand_in",
     {
       title: "Hand it in",
+      outputSchema: handInOut,
+      annotations: ADDS,
       description:
-        "Done here. A task: `markdown`, a transfer guide about what you did, decided and how you " +
-        "checked each Acceptance line — this publishes it and attaches it; its author reviews it. " +
-        "A handoff or a bug: `ok`, whether its Verification held here, and `note` saying what went " +
-        "wrong when it did not. More context than a note holds goes in a follow-up: publish_guide " +
-        "with `parent` set to this id.",
+        "Done here, with proof, sorted against the line it answers. Send `checks`: one entry per " +
+        "line the guide asks for — `## Acceptance` on a task, `## Verification` on a handoff or a " +
+        "bug — each with that line and the evidence for it. That is what its author reads, line " +
+        "against line, instead of hunting through a wall of output for the part that answers each " +
+        "one, AND IT IS HOW YOU KNOW YOU ARE DONE: every line has one. Give a check `cmd` when a " +
+        "command proves it: the command is run here before the hand-in lands, a non-zero exit " +
+        "refuses it, and what it printed is recorded instead of your account of it. Use `ran` for " +
+        "a check no command can settle. `evidence` as one block is the older shape and still " +
+        "works. A task also takes `markdown`, a transfer guide about what you did and decided — " +
+        "this publishes it and attaches it. A handoff or a bug takes `ok`, whether its " +
+        "Verification held here, and `note` saying what went wrong when it did not. DO NOT " +
+        "publish a guide to carry your evidence: it belongs on this call, and a second document " +
+        'titled "Hand-in evidence" is the thing `checks` exists to replace. If it worked but you ' +
+        "had to adapt something, that goes in `writeup` and the next reader of the guide is shown " +
+        "it — that is its home. A follow-up guide is for work somebody else should now do, not " +
+        "for answering.",
       inputSchema: {
         id: z.string().describe("passalong id"),
+        evidence: z
+          .string()
+          .optional()
+          .describe(
+            "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. "it works" is a claim, not evidence',
+          ),
+        checks: z
+          .array(
+            z.object({
+              check: z
+                .string()
+                .describe(
+                  "the line this answers, in the guide's own words: an Acceptance line on a task, " +
+                    "a Verification line on a handoff or a bug",
+                ),
+              ran: z
+                .string()
+                .optional()
+                .describe("what you ran for it, and what came back; not needed when `cmd` is set"),
+              cmd: z
+                .string()
+                .optional()
+                .describe(
+                  "the shell command that proves this line, run here before the hand-in lands — " +
+                    "its exit code decides the check and its output is recorded as the evidence. " +
+                    "Non-zero refuses the hand-in. Leave it out for a check nobody can run, like " +
+                    '"the badge reads 3", and write `ran` instead',
+                ),
+            }),
+          )
+          .optional()
+          .describe(
+            "one entry per line the guide asks for — Acceptance on a task, Verification on a " +
+              "handoff or a bug — in the order you worked them",
+          ),
         ok: z.boolean().optional().describe("handoff or bug: did its Verification hold"),
         note: z.string().optional().describe("one line; required when ok is false"),
+        writeup: z
+          .string()
+          .optional()
+          .describe(
+            "handoff or bug: what you had to adapt to make it work here — a version, a name, a " +
+              "step that needed something the guide does not mention. Prose, and optional: leave " +
+              "it out when it worked as written. The next person to open the guide is shown it, " +
+              "which is why it does not need to be a guide of its own",
+          ),
         markdown: z
           .string()
           .optional()
@@ -604,6 +728,8 @@ export async function serve() {
     "pass",
     {
       title: "Pass it",
+      outputSchema: passOut,
+      annotations: ADDS,
       description:
         "Not yours to do, or you are stuck: give it back with the reason. It is open again for " +
         "the next agent, and the reason goes to whoever is next — say why, or they start where " +
@@ -624,6 +750,7 @@ export async function serve() {
     "get_guide",
     {
       title: "Get guide",
+      annotations: READS,
       description:
         "READ a transfer guide by passalong id or share link and return its full markdown. Also " +
         "writes it to .passalong/<id>.md in the working directory so it survives the session. " +
@@ -648,13 +775,16 @@ export async function serve() {
         // Follow-ups are more context for this guide, so they come with it — after the document,
         // never inside it, so the guide an agent writes back out is still only the guide.
         const context = await passalong.followUps(meta);
+        // The guide this one came out of, in front of the document: a follow-up read on its own
+        // looks like a small piece of work and is a note on a bigger one.
+        const follows = await passalong.parentGuide(meta);
         // After the document, with the other trailing comments, not in front of it. An
         // instruction that arrives with the payload is what gets read — but anything before the
         // opening `---` stops the frontmatter being frontmatter, and this fires on every guide
         // anyone was handed rather than only on bugs. The bug lead stays where it is: it is a
         // warning against executing the document, so being read first is its whole job.
         return text(
-          `${lead}${markdown}${siblings}${context ? `\n\n${context}` : ""}` +
+          `${follows}${lead}${markdown}${siblings}${context ? `\n\n${context}` : ""}` +
             `\n\n<!-- passalong: ${from}; written to ${path} -->` +
             `\n${passalong.handoffNudge(meta)}` +
             `\n${passalong.followUpNote(meta)}`,
@@ -669,6 +799,7 @@ export async function serve() {
     "attach_screenshot",
     {
       title: "Attach a screenshot",
+      annotations: { ...ADDS, openWorldHint: true },
       description:
         "Upload an image from this machine as evidence, and get back the markdown line that " +
         "points at it. Put that line in the guide body — a guide travels as markdown to whoever " +
@@ -697,8 +828,12 @@ export async function serve() {
     "publish_guide",
     {
       title: "Publish guide",
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
       description:
-        "Publish a guide from markdown (frontmatter + sections) — a transfer guide by default, or " +
+        "Publish a guide from markdown (frontmatter + sections). Check what you hold first (take " +
+        "with no id): if this session answers something you hold, hand_in that instead, and if the " +
+        "work never left a branch the team can see, publish what is still open as a bug or a task " +
+        "rather than a write-up of the fix. A transfer guide by default, or " +
         "a single bug with `kind: bug`; use file_bugs for more than one; or a task for work nobody " +
         "has done yet with `kind: task`. Missing id, created, " +
         "author, and source_context are filled in. A screenshot belongs in the markdown: attach it " +
@@ -761,6 +896,7 @@ export async function serve() {
     "file_bugs",
     {
       title: "File bugs",
+      annotations: ADDS,
       description:
         "File one or more bugs you found but are not fixing, as a set. Opens a report and " +
         "publishes each issue as its own guide — its own id, share link, and verdict — so a " +
@@ -846,6 +982,7 @@ export async function serve() {
     "guide_template",
     {
       title: "Guide template",
+      annotations: READS,
       description:
         "The empty guide skeleton with guidance comments for each section. By default a task " +
         "brief: Goal, Context, Constraints, Acceptance, Out of scope. `kind: transfer` gives the " +
@@ -867,6 +1004,7 @@ export async function serve() {
     "set_guide_status",
     {
       title: "Set guide status",
+      annotations: ADDS,
       description:
         "Archive a guide (`consumed`) or put it back on the board (`published`). Archiving is the " +
         "author's shelf: off the board, out of the free tier's count, reversible — it is not a " +
@@ -884,5 +1022,10 @@ export async function serve() {
     },
   );
 
-  await server.connect(new StdioServerTransport());
+  return server;
+}
+
+/** The stdio server: `passalong mcp`, and what `passalong setup` registers with a client. */
+export async function serve() {
+  await buildServer().connect(new StdioServerTransport());
 }