passalong 0.1.0 → 0.2.2

package/README.md

@@ -25,25 +25,72 @@ passalong login      # optional: sync guides across machines and get share links
 ## Commands
 
 ```
-passalong share [file]        publish a guide (newest draft, or a scaffold you edit) → id + link
-passalong pull <id|link>      fetch a guide into ./.passalong/ and print it
-passalong list [query]        your guides, local and synced
+passalong share [file] [--to team[/handle]]  publish a guide → id + link; --to hands it to a team or teammate
+passalong pull <id|link>      fetch a guide into ./.passalong/ (git-ignored) and print it
+passalong inbox               guides handed to you that you have not pulled yet
+passalong board               waiting on you, in flight, landed, worth keeping
+passalong activity [--all]    what happened while you were away; clears unless --all
+passalong list [query]        your guides and your teams', local and synced
 passalong open <id> [--print] view a guide in the browser (or the terminal)
 passalong hub                 open your synced guides in the browser
+passalong works <id>          you tried it and it holds up
+passalong broken <id> <why>   you tried it and it does not — the author is told, with your reason
 passalong done <id>           mark consumed: implemented on the receiving side
 passalong promote <id>        mark promoted: graduated into a reusable reference
 passalong rm <id>             delete a guide locally and from sync
 passalong export [dir]        dump every guide as plain markdown
-passalong login [token]       create an account, or attach this machine to an existing one
+passalong login [token]       create an account, or attach this machine with a token from your hub
+passalong me [--handle H] [--name N] [--email E]   who you are to teammates
+passalong team                current team and its members
+passalong team create <name>  start a team (you become its owner)
+passalong team invite [email] make an invite link (mailed when an email is given)
+passalong team join <link>    accept an invite
+passalong team use <slug>     switch the current team
 passalong setup               install the Claude Code capture skill + register the MCP server
 passalong mcp                 run the MCP server over stdio
 ```
 
+## Teams
+
+A team is the unit of sharing. Members can find, pull, and mark consumed every guide shared to
+the team; a guide can also be handed to one person, who sees it in their inbox (and by email
+when the server has mail configured).
+
+```sh
+passalong me --handle lukman            # how teammates address you
+passalong team create Khaime            # you become owner; "khaime" is now current
+passalong team invite ada@example.com   # or no email: prints a link to send yourself
+passalong team join <link>              # on Ada's machine — or she just opens the link
+passalong share --to khaime/ada         # hand this guide to Ada
+passalong inbox                         # on Ada's side: what was handed to you
+passalong activity                      # back on your side: it landed, and who pulled it
+```
+
+A receiver who tries the work reports back with `passalong works <id>` or `passalong broken <id> <why>`.
+That is separate from `done`, which means *implemented*: a verdict means it actually runs, a failing
+one has to say why, and the author sees it on their board and in their inbox.
+
+Sign in at [the hub](https://passalong.dev/hub) with an email and password, and mint
+an API token there for the CLI and MCP servers — named, revocable, and shown once. Your password
+never goes near the terminal. `passalong login` with no arguments still makes an account without
+any of that; add an email and password later to be able to sign in from a browser and recover it.
+
+Not everyone who receives a guide implements it. Every guide page has a **Verify** view
+(`?view=verify`) that leads with Problem, Verification and Gotchas and folds the implementation
+away — for a tester or anyone checking the work rather than doing it. Invites are accepted in the
+browser, so a teammate needs no terminal to be part of a team.
+
+`passalong activity` is the other half of the transfer: it tells you when someone pulled a guide
+you handed over, when they marked it consumed, and when an invite was taken up. A handoff
+addressed to a person is also emailed; a team-wide share is not, because mail nobody is
+named in is the first thing people filter out. Guides that keep getting pulled get a nudge to
+promote them into the team's small set of maintained references.
+
 ## MCP
 
 `passalong setup` registers the server with Claude Code. For other clients, run `passalong mcp` over stdio.
 
-Tools: `search_guides`, `get_guide`, `publish_guide`, `guide_template`, `set_guide_status`.
+Tools: `search_guides`, `inbox`, `get_guide`, `publish_guide` (with `to`), `guide_template`, `set_guide_status`.
 
 ## Guides are files
 

package/bin/passalong

@@ -1,16 +1,27 @@
 #!/usr/bin/env node
 // Passalong CLI. Few flags on purpose: the defaults are the product.
 //
-//   passalong share [file]        publish a guide (newest draft, or a scaffold you edit) → id + link
+//   passalong share [file] [--to team[/handle]]  publish a guide → id + link; --to hands it to a team or teammate
 //   passalong pull <id|link>      fetch a guide into ./.passalong/ and print it
-//   passalong list [query]        your guides, local and synced
+//   passalong inbox               guides handed to you that you have not pulled yet
+//   passalong board               waiting on you, in flight, landed, worth keeping
+//   passalong activity [--all]    what happened while you were away; clears unless --all
+//   passalong list [query]        your guides and your teams', local and synced
 //   passalong open <id> [--print] view a guide in the browser (or the terminal)
 //   passalong hub                 open your synced guides in the browser
+//   passalong works <id>          you tried it and it holds up
+//   passalong broken <id> <why>   you tried it and it does not — the author is told, with your reason
 //   passalong done <id>           mark consumed: implemented on the receiving side
 //   passalong promote <id>        mark promoted: graduated into a reusable reference
 //   passalong rm <id>             delete a guide locally and from sync
 //   passalong export [dir]        dump every guide as plain markdown (default ./passalong-export)
-//   passalong login [token]       create an account, or attach this machine to an existing one
+//   passalong login [token]       create an account, or attach this machine with a token from your hub
+//   passalong me [--handle H] [--name N] [--email E]   who you are to teammates
+//   passalong team                current team and its members
+//   passalong team create <name>  start a team (you become its owner)
+//   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 setup               install the Claude Code capture skill + register the MCP server
 //   passalong mcp                 run the MCP server over stdio
 import { execFileSync, spawnSync } from "node:child_process";
@@ -53,18 +64,37 @@ function edit(path) {
 }
 
 function openInBrowser(url) {
-  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  const cmd =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
   spawnSync(cmd, [url], { stdio: "ignore", shell: process.platform === "win32" });
 }
 
 function relDate(iso) {
   if (!iso) return "";
   const d = (Date.now() - new Date(iso).getTime()) / 864e5;
-  if (d < 1) return "today";
+  if (d < 1 / 24) return "just now";
+  if (d < 1) return `${Math.floor(d * 24)}h ago`;
   if (d < 30) return `${Math.floor(d)}d ago`;
   return iso.slice(0, 10);
 }
 
+function guideLine(r) {
+  const who = r.team ? `  ${r.team}${r.to ? `/@${r.to}` : ""}${r.mine ? "" : ` from @${r.from || "?"}`}` : "";
+  const tags = r.tags?.length ? `  #${r.tags.join(" #")}` : "";
+  let pulled = "";
+  if (r.mine && r.pulled_by?.length) {
+    const p = r.pulled_by[0];
+    pulled = `  ← ${p.handle ? `@${p.handle}` : "link"} ${relDate(p.at)}${r.pulled_by.length > 1 ? ` +${r.pulled_by.length - 1}` : ""}`;
+  }
+  const nudge = r.mine && r.status === "published" && r.pulls >= 3 ? "  ★ promote?" : "";
+  return `${r.id}  ${r.status.padEnd(9)} ${relDate(r.created).padEnd(10)} ${r.title}${who}${tags}${pulled}${nudge}`;
+}
+
+function activityLine(n) {
+  const dot = n.read ? " " : "•";
+  return `${dot} ${(n.guide || "").padEnd(8)}  ${relDate(n.at).padEnd(10)} ${n.text}`;
+}
+
 const commands = {
   async share(f) {
     let path = f._[0];
@@ -79,15 +109,23 @@ const commands = {
         path = store.draftPath(new Date().toISOString().replace(/[:.]/g, "-"));
         writeFileSync(path, scaffold());
         fromDrafts = true;
-        if (!tty) die(`no draft to share; scaffolded ${path} — fill it in and run \`passalong share ${path}\``);
+        if (!tty)
+          die(`no draft to share; scaffolded ${path} — fill it in and run \`passalong share ${path}\``);
       }
     }
     if (!existsSync(path)) die(`no such file: ${path}`);
     if (tty && !f["no-edit"]) edit(path);
-    const { guide, url, synced, path: saved } = await passalong.share(readFileSync(path, "utf8")).catch((e) => die(e.message));
+    const to = typeof f.to === "string" ? f.to : undefined;
+    const { guide, url, synced, notified, path: saved } = await passalong
+      .share(readFileSync(path, "utf8"), { to })
+      .catch((e) => die(e.message));
     if (fromDrafts) store.removeDraft(path);
     console.log(guide.meta.id);
     console.error(`shared "${guide.meta.title}" → ${saved}`);
+    if (guide.meta.team)
+      console.error(
+        `handed to ${guide.meta.team}${guide.meta.to ? `/@${guide.meta.to}${notified ? " (emailed)" : " (in their inbox)"}` : " (team inbox)"}`,
+      );
     if (synced) console.error(`link: ${url}`);
     else console.error("not synced (run `passalong login` to sync across machines)");
   },
@@ -99,14 +137,56 @@ const commands = {
     console.error(`\npulled from ${from} → ${path}`);
   },
 
+  async inbox() {
+    const rows = await passalong.inbox().catch((e) => die(e.message));
+    if (!rows.length) return console.error("inbox empty — nothing handed to you that you haven't pulled");
+    for (const r of rows) console.log(guideLine(r));
+    console.error(`\n${rows.length} waiting. Pull one with: passalong pull <id>`);
+  },
+
+  async board() {
+    const b = await passalong.board().catch((e) => die(e.message));
+    const queue = (title, note, rows, line) => {
+      if (!rows.length) return;
+      console.log(`\n${title} · ${rows.length}   ${note}`);
+      for (const g of rows) console.log(`  ${g.id}  ${relDate(g.created).padEnd(10)} ${line(g)}`);
+    };
+    queue("Waiting on you", "handed to you, not pulled yet", b.waiting, (g) => `${g.title}  from @${g.from || "?"}`);
+    queue("Not working", "someone tried it and it does not hold up", b.failing, (g) =>
+      `${g.title}  ${g.verdict?.by ? `@${g.verdict.by}` : "someone"}: ${g.verdict?.note || "no reason given"}`);
+    queue("In flight", "handed over, nobody has taken it", b.in_flight, (g) =>
+      `${g.title}  to ${g.team}${g.to ? `/@${g.to}` : ""}${g.stale ? "  ← not picked up" : ""}`);
+    queue("Landed", "someone has it and hasn't said it shipped", b.landed, (g) => `${g.title}  ${g.pulls} pull${g.pulls === 1 ? "" : "s"}`);
+    queue("Worth keeping", "pulled enough to graduate into a reference", b.promote, (g) => `${g.title}  ${g.pulls} pulls`);
+    const total =
+      b.waiting.length + b.failing.length + b.in_flight.length + b.landed.length + b.promote.length;
+    if (!total) console.error("nothing in flight — every transfer is closed");
+    else if (b.unread) console.error(`\n${b.unread} new: passalong activity`);
+  },
+
+  async activity(f) {
+    const { notifications, unread } = await passalong.activity({ all: f.all }).catch((e) => die(e.message));
+    if (!notifications.length)
+      return console.error(
+        f.all ? "nothing has happened yet" : "nothing new — your guides and handoffs are quiet",
+      );
+    for (const n of notifications) console.log(activityLine(n));
+    const waiting = notifications.filter((n) => n.kind === "handoff" && !n.read);
+    if (waiting.length) console.error(`\nPull one with: passalong pull ${waiting[0].guide}`);
+    // Reading the feed is what marks it read: an unread count you have to clear by hand is a
+    // chore, and `--all` is there for when you want to look without clearing.
+    if (!f.all && unread) await passalong.seen().catch(() => {});
+  },
+
   async list(f) {
-    const rows = await passalong.list(f._.join(" "));
+    const scope = typeof f.team === "string" ? f.team : f.mine ? "mine" : "";
+    const rows = await passalong.list(f._.join(" "), { scope });
     if (rows.warning) console.error(`warning: ${rows.warning}`);
-    if (!rows.length) return console.error("no guides yet — run `passalong share` after your next finished piece of work");
-    for (const r of rows) {
-      const tags = r.tags?.length ? `  #${r.tags.join(" #")}` : "";
-      console.log(`${r.id}  ${r.status.padEnd(9)} ${relDate(r.created).padEnd(10)} ${r.title}${tags}`);
-    }
+    if (!rows.length)
+      return console.error(
+        "no guides yet — run `passalong share` after your next finished piece of work",
+      );
+    for (const r of rows) console.log(guideLine(r));
   },
 
   async open(f) {
@@ -122,7 +202,8 @@ const commands = {
   },
 
   async hub() {
-    if (!api.loggedIn()) die("not logged in — run `passalong login` first (the hub shows synced guides)");
+    if (!api.loggedIn())
+      die("not logged in — run `passalong login` first (the hub shows synced guides)");
     // The token rides in the URL fragment: the browser never sends it to the server, and the
     // page moves it into localStorage and scrubs the address bar on load.
     const url = `${api.baseUrl()}/hub#token=${encodeURIComponent(api.token())}`;
@@ -132,6 +213,20 @@ const commands = {
     } else console.log(url);
   },
 
+  async works(f) {
+    const id = f._[0] || die("usage: passalong works <id>");
+    const r = await passalong.verdict(id, true, f._.slice(1).join(" ")).catch((e) => die(e.message));
+    console.error(`${r.id} verified — the author has been told`);
+  },
+
+  async broken(f) {
+    const id = f._[0] || die("usage: passalong broken <id> <what happened>");
+    const why = f._.slice(1).join(" ");
+    if (!why) die("say what went wrong: passalong broken <id> <what happened>");
+    const r = await passalong.verdict(id, false, why).catch((e) => die(e.message));
+    console.error(`${r.id} reported as not working — the author has been told: "${r.note}"`);
+  },
+
   async done(f) {
     const id = f._[0] || die("usage: passalong done <id>");
     const g = await passalong.setStatus(id, "consumed").catch((e) => die(e.message));
@@ -177,7 +272,81 @@ const commands = {
     console.error(`account ${account} created on ${api.baseUrl()}. Sync is on.`);
     console.error("Attach other machines with:");
     console.error(`  passalong login ${token}`);
-    console.error("(the token is the account — keep it private)");
+    console.error("(keep it private — it is a credential, not a password)");
+    console.error("Give teammates a name to address you by: passalong me --handle <you>");
+    console.error(`Add an email and password so you can sign in and recover it: ${api.baseUrl()}/hub`);
+  },
+
+  async me(f) {
+    const patch = {};
+    for (const k of ["handle", "name", "email"]) if (typeof f[k] === "string") patch[k] = f[k];
+    const who = Object.keys(patch).length
+      ? await api.updateMe(patch).then(api.me).catch((e) => die(e.message))
+      : await api.me().catch((e) => die(e.message));
+    console.log(`account  ${who.account}`);
+    console.log(`handle   ${who.handle ? `@${who.handle}` : "(none — set one: passalong me --handle <you>)"}`);
+    if (who.name) console.log(`name     ${who.name}`);
+    if (who.email) console.log(`email    ${who.email}`);
+    console.log(`guides   ${who.guides} synced (${who.limit} active on the free tier)`);
+    const current = store.readConfig().team;
+    console.log(
+      `teams    ${who.teams.length ? who.teams.map((t) => `${t.slug}${t.slug === current ? "*" : ""} (${t.role})`).join(", ") : "(none — passalong team create <name>)"}`,
+    );
+  },
+
+  async team(f) {
+    const [sub, ...rest] = f._;
+    const cfg = store.readConfig();
+    if (!sub) {
+      if (!cfg.team) {
+        const { teams } = await api.teams().catch((e) => die(e.message));
+        if (!teams.length) return console.error("no team yet — passalong team create <name>");
+        return console.error(`you are in ${teams.map((t) => t.slug).join(", ")}; pick one: passalong team use <slug>`);
+      }
+      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)}`);
+      return;
+    }
+    if (sub === "create") {
+      const name = rest.join(" ") || die("usage: passalong team create <name>");
+      const t = await api.createTeam(name).catch((e) => die(e.message));
+      store.writeConfig({ team: t.slug });
+      console.error(`team ${t.name} created as "${t.slug}" — now current. Invite people: passalong team invite [email]`);
+      return;
+    }
+    if (sub === "invite") {
+      const slug = cfg.team || die("no current team — passalong team use <slug>");
+      const inv = await api.invite(slug, rest[0] || "").catch((e) => die(e.message));
+      console.log(inv.url);
+      console.error(
+        inv.email
+          ? inv.mailed
+            ? `emailed ${inv.email}`
+            : `not emailed (mail is not configured on the server) — send ${inv.email} the link above`
+          : "send this link; they run: passalong team join <link>",
+      );
+      return;
+    }
+    if (sub === "join") {
+      const ref = rest[0] || die("usage: passalong team join <link|code>");
+      const code = ref.includes("/") ? ref.split("/").filter(Boolean).pop() : ref;
+      const r = await api.join(code).catch((e) => die(e.message));
+      store.writeConfig({ team: r.slug });
+      console.error(`${r.joined ? "joined" : "already in"} ${r.name} (${r.slug}) — now current`);
+      const who = await api.me().catch(() => null);
+      if (who && !who.handle) console.error("teammates address you by handle: passalong me --handle <you>");
+      return;
+    }
+    if (sub === "use") {
+      const slug = rest[0] || die("usage: passalong team use <slug>");
+      await api.team(slug).catch((e) => die(e.message));
+      store.writeConfig({ team: slug });
+      console.error(`current team: ${slug}`);
+      return;
+    }
+    die("usage: passalong team [create <name> | invite [email] | join <link> | use <slug>]");
   },
 
   async setup() {
@@ -186,15 +355,21 @@ const commands = {
     cpSync(join(PKG, "skill"), skillDir, { recursive: true });
     console.error(`installed Claude Code skill → ${skillDir}`);
     try {
-      execFileSync("claude", ["mcp", "add", "--scope", "user", "passalong", "--", "passalong", "mcp"], { stdio: "pipe" });
+      execFileSync("claude", ["mcp", "add", "--scope", "user", "passalong", "--", "passalong", "mcp"], {
+        stdio: "pipe",
+      });
       console.error("registered MCP server: claude mcp add passalong -- passalong mcp");
     } catch (err) {
       const msg = String(err.stderr || err.message);
       if (/already exists/i.test(msg)) console.error("MCP server already registered");
-      else console.error(`could not register MCP server automatically (${msg.trim()}).\n  run: claude mcp add passalong -- passalong mcp`);
+      else
+        console.error(
+          `could not register MCP server automatically (${msg.trim()}).\n  run: claude mcp add passalong -- passalong mcp`,
+        );
     }
-    if (!api.loggedIn()) console.error("sync is off; run `passalong login` when you want guides to follow you across machines");
-    console.error("done. In Claude Code, say \"pass this along\" at the end of a task, or run /passalong-capture.");
+    if (!api.loggedIn())
+      console.error("sync is off; run `passalong login` when you want guides to follow you across machines");
+    console.error('done. In Claude Code, say "pass this along" at the end of a task, or run /passalong-capture.');
   },
 
   async mcp() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "Hand a finished implementation from one context to another, in a form an AI agent can act on.",
   "keywords": [
     "mcp",
@@ -11,7 +11,7 @@
     "cli",
     "markdown"
   ],
-  "homepage": "https://passalong.kreativekorna.com",
+  "homepage": "https://passalong.dev",
   "repository": {
     "type": "git",
     "url": "https://github.com/codellyson/passalong.git",

package/skill/SKILL.md

@@ -11,22 +11,29 @@ session's history. Write for execution, not for permanence.
 
 ## Procedure
 
-1. **Reconstruct the story from the session.** What was the problem, what was tried, what failed,
+1. **Pick the one thing to transfer.** If the user named it (`/passalong-capture <what>` or
+   "pass along the webhook fix"), that is the scope. Otherwise take the most recent completed
+   piece of work. A long session usually holds several; do not merge them, and if it is
+   genuinely unclear which one the user means, ask before writing.
+2. **Reconstruct the story from the session.** What was the problem, what was tried, what failed,
    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.
-2. **Write the guide** with the structure below. Be concrete: file paths, commands, exact error
+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.
-3. **Mark context-specific parts** so the receiver can adapt rather than copy. Put
+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.
-4. **Save the draft** to `~/.passalong/drafts/<slug>.md` (create the directory if needed), then run:
+5. **Save the draft** to `~/.passalong/drafts/<slug>.md` (create the directory if needed), then run:
 
    ```bash
    passalong share ~/.passalong/drafts/<slug>.md --no-edit
    ```
 
-   It prints the guide id on stdout and the share link on stderr.
-5. **Report** the id (and link if synced) and one line on how to use it on the other side:
+   If the user named a person or team ("share this with Ada", "hand this to the platform
+   team"), add `--to <team>` or `--to <team>/<handle>`; `passalong team` lists the current
+   team's members and their handles. It prints the guide id on stdout and the share link (and
+   who it was handed to) on stderr.
+6. **Report** the id (and link if synced) and one line on how to use it on the other side:
    `passalong pull <id>` in the target repo, or "pull passalong <id>" to an agent with the Passalong MCP server.
 
 If the `passalong` command is missing, tell the user to run `npm i -g passalong && passalong setup` and
@@ -70,6 +77,8 @@ Commands to run and what they should print. Test cases. What "done" looks like.
   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.
+- **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.
 - **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.

package/src/api.js

@@ -1,8 +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 a NotLoggedIn the CLI turns into a hint.
+// CLI is a purely local tool, and every function throws an ApiError the CLI turns into a hint.
 import { readConfig } from "./store.js";
 
-export const DEFAULT_API = "https://passalong.kreativekorna.com";
+export const DEFAULT_API = "https://passalong.dev";
 
 export class ApiError extends Error {
   constructor(status, message) {
@@ -54,16 +54,42 @@ async function call(path, { method = "GET", body, auth = true, raw = false } = {
   return raw ? res.text() : res.json();
 }
 
+const q = (params) => {
+  const s = new URLSearchParams(Object.entries(params).filter(([, v]) => v)).toString();
+  return s ? `?${s}` : "";
+};
+
 /** Mint a fresh account and return its token. No email, no password: the token is the account. */
 export const createAccount = () => call("/v1/accounts", { method: "POST", auth: false });
 export const me = () => call("/v1/me");
+export const updateMe = (patch) => call("/v1/me", { method: "PATCH", body: patch });
+
+export const teams = () => call("/v1/teams");
+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 join = (code) =>
+  call(`/v1/invites/${encodeURIComponent(code)}/accept`, { method: "POST" });
+
+export const board = () => call("/v1/board");
+export const notifications = ({ unread = true, limit = 0 } = {}) =>
+  call(`/v1/notifications${q({ unread: unread ? "1" : "", limit: limit || "" })}`);
+/** No ids means "everything unread". */
+export const markRead = (ids = []) =>
+  call("/v1/notifications/read", { method: "POST", body: { ids } });
+
 export const publish = (id, markdown) =>
   call(`/v1/guides/${id}`, { method: "PUT", body: markdown });
-export const list = (q = "") => call(`/v1/guides${q ? `?q=${encodeURIComponent(q)}` : ""}`);
+export const list = (query = "", scope = "") => call(`/v1/guides${q({ q: query, scope })}`);
+export const inbox = () => call("/v1/inbox");
 export const get = (id) => call(`/v1/guides/${id}`, { raw: true });
 export const setStatus = (id, status) =>
   call(`/v1/guides/${id}/status`, { method: "PATCH", body: { status } });
 export const remove = (id) => call(`/v1/guides/${id}`, { method: "DELETE" });
+/** Does it actually work? `note` is required when it does not. */
+export const verdict = (id, ok, note = "") =>
+  call(`/v1/guides/${id}/verdict`, { method: "PUT", body: { ok, note } });
 
 /** Fetch a guide by its share link (no account needed). Accepts the web URL or the .md URL. */
 export async function fetchShared(url) {

package/src/guide.js

@@ -92,6 +92,8 @@ const META_ORDER = [
   "author",
   "source_context",
   "status",
+  "team",
+  "to",
   "stack_assumptions",
   "tags",
 ];

package/src/mcp.js

@@ -1,5 +1,6 @@
-// The Passalong MCP server (stdio). This is the rail that makes Passalong tool-agnostic: any MCP-capable
-// agent can search, pull, and publish guides without leaving its session.
+// The Passalong MCP server (stdio). This is the rail that makes Passalong tool-agnostic: any
+// MCP-capable agent can search, pull, and publish guides without leaving its session. With a
+// team, the same tools see the team's guides and the user's inbox.
 //
 //   claude mcp add passalong -- passalong mcp
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -14,16 +15,20 @@ const fail = (err) => ({ content: [{ type: "text", text: err.message }], isError
 
 export async function serve() {
   const server = new McpServer(
-    { name: "passalong", version: "0.1.0" },
+    { name: "passalong", version: "0.2.0" },
     {
       instructions:
-        "Passalong hands finished implementations between contexts as transfer guides: markdown with " +
-        `frontmatter and the sections ${SECTIONS.join(", ")}. ` +
-        "When the user references a passalong id or link, call get_guide and follow its Steps, adapting " +
-        "anything marked ASSUMES to this codebase; run its Verification before declaring done. " +
-        "When the user asks to share, hand off, or passalong what was just done, distill the session " +
-        "into a guide (guide_template shows the shape) and call publish_guide. Gotchas are the " +
-        "highest-value section: record what failed and why.",
+        "Passalong hands finished implementations between contexts as transfer guides: markdown " +
+        `with frontmatter and the sections ${SECTIONS.join(", ")}. ` +
+        "When the user references a passalong id or link, call get_guide and follow its Steps, " +
+        "adapting anything marked ASSUMES to this codebase; run its Verification before declaring " +
+        "done, then set_guide_status consumed and verify_guide with the result. " +
+        "When the user asks to pass along, hand off, or " +
+        "share what was just done, distill the session into a guide (guide_template shows the " +
+        "shape) and call publish_guide, with `to` as team or team/handle when it is for a teammate. " +
+        "At the start of work, inbox shows guides teammates have handed to this user, and activity " +
+        "shows whether the guides they handed off have landed. Gotchas are " +
+        "the highest-value section: record what failed and why.",
     },
   );
 
@@ -32,13 +37,16 @@ export async function serve() {
     {
       title: "Search guides",
       description:
-        "Search the user's transfer guides (local and synced) by words in the title, tags, stack, " +
-        "or body. Empty query lists everything, newest first.",
-      inputSchema: { query: z.string().default("") },
+        "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.",
+      inputSchema: {
+        query: z.string().default(""),
+        scope: z.string().optional().describe('"mine", "all" (default), or a team slug'),
+      },
     },
-    async ({ query }) => {
+    async ({ query, scope }) => {
       try {
-        const rows = await passalong.list(query);
+        const rows = await passalong.list(query, { scope: scope || "" });
         return json({ guides: rows, warning: rows.warning });
       } catch (err) {
         return fail(err);
@@ -46,13 +54,103 @@ export async function serve() {
     },
   );
 
+  server.registerTool(
+    "inbox",
+    {
+      title: "Inbox",
+      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).",
+      inputSchema: {},
+    },
+    async () => {
+      try {
+        return json({ guides: await passalong.inbox() });
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "board",
+    {
+      title: "Board",
+      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 " +
+        "(handed over, nobody has taken it — `stale` means it has sat over a week), landed " +
+        "(someone has it and has not marked it consumed), and worth keeping (pulled enough to " +
+        "promote into a reference). Use it to answer 'what is outstanding?'.",
+      inputSchema: {},
+    },
+    async () => {
+      try {
+        return json(await passalong.board());
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "verify_guide",
+    {
+      title: "Report whether a guide works",
+      description:
+        "After following a guide's Verification section, report the result. This is the only way " +
+        "the author learns their handoff did not land — `set_guide_status consumed` says it was " +
+        "implemented, this says it actually works. A failing verdict must say what went wrong.",
+      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); one line, max 280 chars"),
+      },
+    },
+    async ({ id, ok, note }) => {
+      try {
+        return json(await passalong.verdict(id, ok, note || ""));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "activity",
+    {
+      title: "Activity",
+      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.",
+      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 }) => {
+      try {
+        const res = await passalong.activity({ all });
+        if (mark_read && res.unread) await passalong.seen();
+        return json(res);
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
   server.registerTool(
     "get_guide",
     {
       title: "Get guide",
       description:
-        "Fetch 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.",
+        "Fetch 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. " +
+        "Pulling a teammate's guide tells them the transfer landed.",
       inputSchema: {
         ref: z.string().describe("passalong id (e.g. k3mq2xa7) or share URL"),
         cwd: z
@@ -77,21 +175,33 @@ export async function serve() {
       title: "Publish guide",
       description:
         "Publish a transfer guide from markdown (frontmatter + sections). Missing id, created, " +
-        "author, and source_context are filled in. Returns the id and share link.",
+        'author, and source_context are filled in. `to` addresses it to a team ("khaime") or a ' +
+        'teammate ("khaime/lukman"), who is notified. Returns the id and share link.',
       inputSchema: {
         markdown: z.string().describe("full guide markdown; start from guide_template"),
+        to: z.string().optional().describe("team slug, or team/handle for a specific teammate"),
         cwd: z
           .string()
           .optional()
           .describe("directory the work happened in, used to infer source_context"),
       },
     },
-    async ({ markdown, cwd }) => {
+    async ({ markdown, to, cwd }) => {
       try {
-        const { guide, url, synced, path } = await passalong.share(markdown, {
+        const { guide, url, synced, notified, path } = await passalong.share(markdown, {
           cwd: cwd || process.cwd(),
+          to,
+        });
+        return json({
+          id: guide.meta.id,
+          title: guide.meta.title,
+          url,
+          synced,
+          team: guide.meta.team || "",
+          to: guide.meta.to || "",
+          notified,
+          path,
         });
-        return json({ id: guide.meta.id, title: guide.meta.title, url, synced, path });
       } catch (err) {
         return fail(err);
       }
@@ -113,7 +223,8 @@ export async function serve() {
     {
       title: "Set guide status",
       description:
-        "Mark a guide consumed (implemented on the receiving side) or promoted (a reusable reference).",
+        "Mark a guide consumed (implemented on the receiving side) or promoted (a reusable reference). " +
+        "Only the author can promote.",
       inputSchema: { id: z.string(), status: z.enum(["published", "consumed", "promoted"]) },
     },
     async ({ id, status }) => {

package/src/passalong.js

@@ -1,6 +1,6 @@
-// The operations Passalong exposes. Both surfaces (bin/passalong and the MCP server) call these, so
-// anything an agent can do through MCP a human can do from the terminal and vice versa.
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+// The operations Passalong exposes. Both surfaces (bin/passalong and the MCP server) call these,
+// so anything an agent can do through MCP a human can do from the terminal and vice versa.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import * as api from "./api.js";
 import { context } from "./capture.js";
@@ -9,11 +9,18 @@ import * as store from "./store.js";
 
 export class PassalongError extends Error {}
 
+/** "team" or "team/handle" → { team, to }. */
+export function parseTarget(to) {
+  if (!to) return {};
+  const [team, handle] = String(to).split("/");
+  return { team: team.trim(), to: handle ? handle.trim().replace(/^@/, "") : undefined };
+}
+
 /**
  * Publish a guide from markdown: fill in defaults, validate, store locally, and sync when
- * logged in. Returns { guide, path, url, synced }.
+ * logged in. `to` addresses it: "team" or "team/handle". Returns { guide, path, url, synced }.
  */
-export async function share(markdown, { cwd = process.cwd() } = {}) {
+export async function share(markdown, { cwd = process.cwd(), to } = {}) {
   const c = context(cwd);
   const raw = parse(markdown);
   let guide = stamp(
@@ -23,6 +30,11 @@ export async function share(markdown, { cwd = process.cwd() } = {}) {
       source_context: c.branch && c.branch !== "HEAD" ? `${c.name}@${c.branch}` : c.name,
     },
   );
+  const target = parseTarget(to);
+  if (target.team) guide.meta.team = target.team;
+  if (target.to) guide.meta.to = target.to;
+  if (guide.meta.to && !guide.meta.team)
+    throw new PassalongError("`to:` needs a team — address a handoff as team/handle");
   const errors = validate(guide);
   if (errors.length)
     throw new PassalongError(`guide is not ready to share:\n  - ${errors.join("\n  - ")}`);
@@ -31,14 +43,18 @@ export async function share(markdown, { cwd = process.cwd() } = {}) {
 
   let url = guide.meta.url || null;
   let synced = false;
+  let notified = false;
   if (api.loggedIn()) {
     const res = await api.publish(guide.meta.id, serialize(guide));
     url = res.url;
     synced = true;
+    notified = Boolean(res.notified);
     guide = { ...guide, meta: { ...guide.meta, url } };
+  } else if (guide.meta.team) {
+    throw new PassalongError("sharing to a team needs sync — run `passalong login` first");
   }
   const path = store.save(guide);
-  return { guide, path, url, synced };
+  return { guide, path, url, synced, notified };
 }
 
 /** Resolve a reference (id, share URL, or local file path) to a guide. */
@@ -48,7 +64,6 @@ export async function resolve(ref) {
     return { guide: parse(md), from: "link" };
   }
   if (ref.endsWith(".md") && existsSync(ref)) {
-    const { readFileSync } = await import("node:fs");
     return { guide: parse(readFileSync(ref, "utf8")), from: "file" };
   }
   if (!ID_RE.test(ref))
@@ -71,15 +86,25 @@ export async function resolve(ref) {
 }
 
 /**
- * Pull a guide into a working directory: writes .passalong/<id>.md there and returns the guide so
- * the caller can put the text straight into an agent's context.
+ * Pull a guide into a working directory: writes .passalong/<id>.md there and returns the guide
+ * so the caller can put the text straight into an agent's context. A pull of someone else's
+ * guide is also recorded server-side, which is how the sender sees the transfer landed.
  */
 export async function pull(ref, { cwd = process.cwd(), write = true } = {}) {
   const { guide, from } = await resolve(ref);
+  // A locally cached copy of a teammate's guide still counts as a pull for them.
+  if (from === "local" && api.loggedIn() && guide.meta.team) {
+    api.get(guide.meta.id).catch(() => {});
+  }
   let path = null;
   if (write) {
     const dir = join(cwd, ".passalong");
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    // A pulled guide carries its own share URL in the frontmatter, and that URL needs no account
+    // to read. Committing this directory would publish the guide to anyone who can see the repo,
+    // so the directory ignores itself. Delete this file if you do want guides in the repo.
+    const ignore = join(dir, ".gitignore");
+    if (!existsSync(ignore)) writeFileSync(ignore, "*\n");
     path = join(dir, `${guide.meta.id}.md`);
     writeFileSync(path, serialize(guide));
   }
@@ -87,20 +112,17 @@ export async function pull(ref, { cwd = process.cwd(), write = true } = {}) {
 }
 
 /** Local guides merged with synced ones (by id), newest first, optionally filtered. */
-export async function list(query = "", { remote = true } = {}) {
-  const local = store.search(query);
+export async function list(query = "", { remote = true, scope = "" } = {}) {
+  const local = scope && scope !== "all" && scope !== "mine" ? [] : store.search(query);
   const seen = new Set(local.map((g) => g.meta.id));
   const rows = local.map((g) => ({ ...summary(g), where: "local" }));
   if (remote && api.loggedIn()) {
     try {
-      const res = await api.list(query);
+      const res = await api.list(query, scope);
       for (const r of res.guides) {
-        if (seen.has(r.id)) {
-          const row = rows.find((x) => x.id === r.id);
-          row.where = "synced";
-          row.url = r.url;
-          row.pulls = r.pulls;
-        } else rows.push({ ...r, where: "synced" });
+        const row = seen.has(r.id) ? rows.find((x) => x.id === r.id) : null;
+        if (row) Object.assign(row, r, { where: "synced" });
+        else rows.push({ ...r, where: "synced" });
       }
     } catch (err) {
       rows.warning = `sync unavailable: ${err.message}`;
@@ -109,6 +131,42 @@ export async function list(query = "", { remote = true } = {}) {
   return rows.sort((a, b) => (b.created || "").localeCompare(a.created || ""));
 }
 
+/** Guides handed to you (or your teams) that you have not pulled yet. Needs sync. */
+export async function inbox() {
+  const res = await api.inbox();
+  return res.guides;
+}
+
+/**
+ * The state of your transfers as four queues: waiting on you, in flight (handed over, untouched),
+ * landed (someone has it, not closed), and worth keeping (pulled enough to promote). Needs sync.
+ */
+export const board = () => api.board();
+
+/**
+ * What happened while you were away: your guides being pulled and shipped, guides handed to you,
+ * invites taken up. Each item carries a rendered `text` line so every surface says the same thing.
+ */
+export async function activity({ all = false, limit = 50 } = {}) {
+  return api.notifications({ unread: !all, limit });
+}
+
+/**
+ * Report whether a guide actually works. This is the reader's answer, not the author's status:
+ * `done` says "I implemented it", a verdict says "I tried it and it holds up" — or does not.
+ * A failing verdict needs a note; "it doesn't work" without a reason helps nobody.
+ */
+export async function verdict(id, ok, note = "") {
+  if (!api.loggedIn()) throw new PassalongError("verdicts need sync — run `passalong login` first");
+  if (!ok && !note.trim())
+    throw new PassalongError("say what went wrong: passalong failed <id> <what happened>");
+  const { guide } = await resolve(id);
+  return api.verdict(guide.meta.id, ok, note.trim());
+}
+
+/** Mark notifications seen. No ids means everything unread. */
+export const seen = (ids = []) => api.markRead(ids);
+
 export function summary(g) {
   return {
     id: g.meta.id,
@@ -119,6 +177,9 @@ export function summary(g) {
     tags: g.meta.tags || [],
     stack_assumptions: g.meta.stack_assumptions || [],
     url: g.meta.url || null,
+    team: g.meta.team || "",
+    to: g.meta.to || "",
+    mine: true,
   };
 }
 
@@ -134,7 +195,7 @@ export async function setStatus(id, status) {
 }
 
 export async function remove(id) {
-  store.remove(id);
+  // Server first: if it refuses (not the author), the local copy must survive too.
   if (api.loggedIn()) {
     try {
       await api.remove(id);
@@ -142,6 +203,7 @@ export async function remove(id) {
       if (err.status !== 404) throw err;
     }
   }
+  store.remove(id);
 }
 
 /** Write every local guide to a directory as plain markdown. Returns the paths written. */