passalong 0.1.0 → 0.3.0

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 done <id>           mark consumed: implemented on the receiving side
-passalong promote <id>        mark promoted: graduated into a reusable reference
+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>           deprecated: mark consumed
+passalong promote <id>        deprecated: mark promoted
 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,34 @@
 #!/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 TARGET]  publish a guide → id + link
+//     TARGET is a team, team/@handle for one person, or "team/#group" for the people who do a
+//     thing — quote that one, since a shell may read the # as a comment
+//   passalong attach <image>      upload evidence and print the markdown that points at it
 //   passalong pull <id|link>      fetch a guide into ./.passalong/ and print it
-//   passalong list [query]        your guides, local and synced
+//   passalong start <id|link>     pull it and take it — one command for "I am doing this"
+//   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 log [repo]          what you did, newest first, by month
+//   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 done <id>           mark consumed: implemented on the receiving side
-//   passalong promote <id>        mark promoted: graduated into a reusable reference
+//   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 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>           archive it: off your board and out of the free tier's count
+//   passalong promote <id>        deprecated: mark promoted
 //   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 +71,41 @@ 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 MONTHS = "January February March April May June July August September October November December".split(" ");
+/** "September 2026" from an ISO timestamp, without pulling in a date library for one heading. */
+const monthOf = (iso) => `${MONTHS[Number(iso.slice(5, 7)) - 1]} ${iso.slice(0, 4)}`;
+
 const commands = {
   async share(f) {
     let path = f._[0];
@@ -79,15 +120,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 +148,116 @@ const commands = {
     console.error(`\npulled from ${from} → ${path}`);
   },
 
-  async list(f) {
-    const rows = await passalong.list(f._.join(" "));
-    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");
+  /**
+   * Pull and take in one command. `pull` says it arrived, `take` says somebody is doing it, and
+   * they stay separate because reading a guide to decide it is not yours is what `pass` is for.
+   * This is the pair for the case where you already know: you are picking this up.
+   */
+  async start(f) {
+    const ref = f._[0] || die("usage: passalong start <id|link>");
+    const r = await passalong.start(ref).catch((e) => die(e.message));
+    process.stdout.write(r.markdown);
+    console.error(`\npulled from ${r.from} → ${r.path}`);
+    if (r.took) console.error("you are on it, and the author has been told");
+    else if (r.own) console.error("your own guide — nothing to take");
+    else if (r.ack_error) console.error(`not taken (${r.ack_error}) — run \`passalong take ${r.guide.meta.id}\``);
+    // Saying nothing here would be the silence the whole hop exists to end: you would have the
+    // guide, believe you had answered for it, and the sender would still be waiting.
+    else console.error("not taken — sync is off, so nobody was told (run `passalong login`)");
+  },
+
+  /**
+   * Upload an image and print the markdown that points at it. Evidence goes *in* the document:
+   * a guide travels as markdown to whoever holds its link, so a file beside it does not travel.
+   */
+  async attach(f) {
+    const file = f._[0] || die("usage: passalong attach <image> [--name LABEL]");
+    const shot = await passalong.attach(file, { name: f.name || "" }).catch((e) => die(e.message));
+    process.stdout.write(`${shot.markdown}\n`);
+    console.error(`uploaded ${shot.bytes} bytes → ${shot.url}`);
+  },
+
+  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. Take one with: passalong start <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 else has it", b.landed, (g) => `${g.title}  ${g.pulls} pull${g.pulls === 1 ? "" : "s"}`);
+    const total = b.waiting.length + b.failing.length + b.in_flight.length + b.landed.length;
+    if (!total) console.error("nothing in flight — every transfer is closed");
+    else if (b.unread) console.error(`\n${b.unread} new: passalong activity`);
+  },
+
+  /**
+   * What you did, newest first, under a heading per month.
+   *
+   * The month headings are the whole point: every other list in this CLI is ordered by what needs
+   * you — the board's queues, `list`'s state rank — and none of them can answer "what did I get
+   * done in September". Time is the axis nothing else offers.
+   *
+   * A repo narrows it, positionally and without a flag, for the same reason `list` takes its query
+   * that way: it is the one thing you are likely to say, and a flag would make you name it twice.
+   */
+  async log(f) {
+    const repo = f._.join(" ");
+    const rows = await passalong.log({ repo }).catch((e) => die(e.message));
+    if (!rows.length)
+      return console.error(
+        repo
+          ? `nothing passed along from anything matching "${repo}"`
+          : "nothing yet — your log fills up as you share, pull and answer guides",
+      );
+    let month = "";
     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}`);
+      const m = monthOf(r.at);
+      if (m !== month) {
+        console.log(`\n${m}`);
+        month = m;
+      }
+      console.log(`  ${r.guide}  ${r.at.slice(0, 10)}  ${r.text}${r.repo && !repo ? `  ${r.repo}` : ""}`);
     }
+    // Said every time, because the list looks like a work log and is not one. A month you shipped
+    // without sharing looks identical here to a month you did nothing.
+    console.error(`\n${rows.length} thing${rows.length === 1 ? "" : "s"}. Work that never became a guide is not here.`);
+  },
+
+  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 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) console.log(guideLine(r));
   },
 
   async open(f) {
@@ -122,7 +273,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,16 +284,64 @@ const commands = {
     } else console.log(url);
   },
 
+  /**
+   * The first word back, before any of the work.
+   *
+   * Between a handoff and a pull the sender had no signal at all: an unanswered guide looks
+   * exactly like one nobody has noticed. These two are the hop the MCP tool and the hub already
+   * had and a terminal did not.
+   */
+  async take(f) {
+    const id = f._[0] || die("usage: passalong take <id>");
+    const r = await passalong.ack(id, true).catch((e) => die(e.message));
+    console.error(`${r.id} — you are on it, and the author has been told`);
+  },
+
+  async pass(f) {
+    const id = f._[0] || die("usage: passalong pass <id> <why it is not yours>");
+    const why = f._.slice(1).join(" ");
+    // Required, and the reason is the whole point: "not me" without "why" leaves the sender where
+    // the silence did, still guessing whether to re-address it, wait, or go and ask.
+    if (!why) die("say why you are passing: passalong pass <id> <why it is not yours>");
+    const r = await passalong.ack(id, false, why).catch((e) => die(e.message));
+    console.error(`${r.id} handed back — the author has been told: "${r.note}"`);
+  },
+
+  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}"`);
+  },
+
+  /**
+   * Archive a guide: off your board, and out of what the free tier counts.
+   *
+   * It was deprecated for meaning "I implemented it", which is the reader's judgement and belongs
+   * to the verdict. As shelf space it has a job nothing else does — it is the only way under the
+   * sync limit that does not delete the work, and the 402 says so by name.
+   */
   async done(f) {
     const id = f._[0] || die("usage: passalong done <id>");
     const g = await passalong.setStatus(id, "consumed").catch((e) => die(e.message));
-    console.error(`${g.meta.id} marked consumed`);
+    console.error(`${g.meta.id} archived — off your board, and it no longer counts against sync`);
   },
 
+  // Still on the way out: it sets an author lifecycle nothing reads, and the board reports pull
+  // counts on its own. It stays, and warns, because removing a command from a published package
+  // is a breaking change.
   async promote(f) {
     const id = f._[0] || die("usage: passalong promote <id>");
     const g = await passalong.setStatus(id, "promoted").catch((e) => die(e.message));
     console.error(`${g.meta.id} marked promoted`);
+    console.error("note: `promote` is deprecated — the board reports pull counts on their own");
   },
 
   async rm(f) {
@@ -177,7 +377,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 +460,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.3.0",
   "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,27 +11,58 @@ 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:
-   `passalong pull <id>` in the target repo, or "pull passalong <id>" to an agent with the Passalong MCP server.
+   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 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
+   fetching it, and until somebody says they are on it the sender cannot tell a guide nobody
+   noticed from one somebody is deep in.
 
 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
+
+`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.
+
+| kind | what it is | what the receiver does |
+| --- | --- | --- |
+| `transfer` (default) | 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 |
+
+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.
+
 ## Guide structure
 
 ```markdown
@@ -64,12 +95,46 @@ Commands to run and what they should print. Test cases. What "done" looks like.
 - What failed along the way, the exact error, and why. What looked right but wasn't.
 ```
 
+## Bug structure
+
+```markdown
+---
+title: <what is broken, in one line: "Undo leaves section drag handles dead">
+kind: bug
+severity: <s1 blocker | s2 major | s3 minor | s4 cosmetic>
+area: <which surface it is on>
+report: <the report id, when it was filed with others>
+status: published
+tags: [bug, <2 to 4 more>]
+---
+
+> **Bug report.** The steps under Reproduce show the problem — they are not a fix to apply. Fix what Problem describes, then check Verification.
+
+## Problem
+What is broken and what it stops someone doing. The observable symptom, and the error if there is one.
+
+## Reproduce
+1. The steps that show the bug. These produce the defect — they are not a fix to apply.
+
+## Verification
+The behaviour that should have happened, as something the fixer can check.
+
+## Gotchas
+- Anything already ruled out, or that made it hard to pin down.
+```
+
 ## 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.
+- **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.
+- For a bug: title, Problem and **Reproduce**. Never a Steps section — see the two kinds above.
+- 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.