passalong 0.2.2 → 0.3.0

package/README.md

@@ -35,8 +35,8 @@ 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 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 with a token from your hub

package/bin/passalong

@@ -1,18 +1,25 @@
 #!/usr/bin/env node
 // Passalong CLI. Few flags on purpose: the defaults are the product.
 //
-//   passalong share [file] [--to team[/handle]]  publish a guide → id + link; --to hands it to a team or teammate
+//   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 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 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>           mark consumed: implemented on the receiving side
-//   passalong promote <id>        mark promoted: graduated into a reusable reference
+//   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 with a token from your hub
@@ -95,6 +102,10 @@ function activityLine(n) {
   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];
@@ -137,11 +148,40 @@ const commands = {
     console.error(`\npulled from ${from} → ${path}`);
   },
 
+  /**
+   * 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. Pull one with: passalong pull <id>`);
+    console.error(`\n${rows.length} waiting. Take one with: passalong start <id>`);
   },
 
   async board() {
@@ -156,14 +196,45 @@ const commands = {
       `${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;
+    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 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)
@@ -213,6 +284,29 @@ 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));
@@ -227,16 +321,27 @@ const commands = {
     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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.2.2",
+  "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",

package/skill/SKILL.md

@@ -34,11 +34,35 @@ session's history. Write for execution, not for permanence.
    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.
+   `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
@@ -71,6 +95,34 @@ 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
@@ -82,3 +134,7 @@ Commands to run and what they should print. Test cases. What "done" looks like.
 - **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.

package/src/api.js

@@ -73,6 +73,9 @@ export const join = (code) =>
   call(`/v1/invites/${encodeURIComponent(code)}/accept`, { method: "POST" });
 
 export const board = () => call("/v1/board");
+/** What you did, newest first. `since` is a date prefix: 2026, 2026-09, 2026-09-11. */
+export const log = ({ repo = "", since = "", limit = 0 } = {}) =>
+  call(`/v1/log${q({ repo, since, limit: limit || "" })}`);
 export const notifications = ({ unread = true, limit = 0 } = {}) =>
   call(`/v1/notifications${q({ unread: unread ? "1" : "", limit: limit || "" })}`);
 /** No ids means "everything unread". */
@@ -83,6 +86,10 @@ export const publish = (id, markdown) =>
   call(`/v1/guides/${id}`, { method: "PUT", body: markdown });
 export const list = (query = "", scope = "") => call(`/v1/guides${q({ q: query, scope })}`);
 export const inbox = () => call("/v1/inbox");
+/** Open a report for a set of issues to be filed under. */
+export const createReport = (body) => call("/v1/reports", { method: "POST", body });
+/** One report and the issues filed under it, grouped by product area. */
+export const report = (id) => call(`/v1/reports/${encodeURIComponent(id)}`);
 export const get = (id) => call(`/v1/guides/${id}`, { raw: true });
 export const setStatus = (id, status) =>
   call(`/v1/guides/${id}/status`, { method: "PATCH", body: { status } });
@@ -91,6 +98,40 @@ export const remove = (id) => call(`/v1/guides/${id}`, { method: "DELETE" });
 export const verdict = (id, ok, note = "") =>
   call(`/v1/guides/${id}/verdict`, { method: "PUT", body: { ok, note } });
 
+export const ack = (id, taken, note = "") =>
+  call(`/v1/guides/${id}/ack`, { method: "PUT", body: { taken, note } });
+
+/**
+ * Upload an image as evidence, and get back the URL a guide points at.
+ *
+ * Not `call()`: that serialises a body as JSON or markdown, and this route reads bytes and takes
+ * the content type as the declaration of what they are. `name` is the label, and it travels in a
+ * header rather than the body for the same reason.
+ */
+export async function uploadShot(bytes, type, name = "") {
+  const t = token();
+  if (!t) throw new ApiError(401, "not logged in — run `passalong login` to enable sync");
+  const headers = { authorization: `Bearer ${t}`, "content-type": type };
+  // A header is latin-1: a filename with an accent in it throws on the way out rather than at the
+  // server, and the label is not worth failing an upload over.
+  if (name) headers["x-shot-name"] = String(name).replace(/[^\x20-\x7e]/g, "");
+  let res;
+  try {
+    res = await fetch(`${baseUrl()}/v1/shots`, { method: "POST", headers, body: bytes });
+  } catch (err) {
+    throw new ApiError(0, `could not reach ${baseUrl()} (${err.message})`);
+  }
+  if (!res.ok) {
+    const body = await res.text();
+    let message = body;
+    try {
+      message = JSON.parse(body).message || body;
+    } catch {}
+    throw new ApiError(res.status, message || res.statusText);
+  }
+  return (await res.json()).shot;
+}
+
 /** Fetch a guide by its share link (no account needed). Accepts the web URL or the .md URL. */
 export async function fetchShared(url) {
   const u = new URL(url);