passalong 0.3.0 → 0.3.2

package/README.md

@@ -48,6 +48,7 @@ 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
+passalong version             print the installed version (also -v, --version)
 ```
 
 ## Teams

package/bin/passalong

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // Passalong CLI. Few flags on purpose: the defaults are the product.
 //
-//   passalong share [file] [--to TARGET]  publish a guide → id + link
+//   passalong share [file] [--to TARGET] [--follows ID]  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
@@ -19,7 +19,6 @@
 //   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 with a token from your hub
@@ -31,6 +30,7 @@
 //   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
+//   passalong version             print the installed version (also -v, --version)
 import { execFileSync, spawnSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -93,8 +93,7 @@ function guideLine(r) {
     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}`;
+  return `${r.id}  ${r.status.padEnd(9)} ${relDate(r.created).padEnd(10)} ${r.title}${who}${tags}${pulled}`;
 }
 
 function activityLine(n) {
@@ -127,12 +126,14 @@ const commands = {
     if (!existsSync(path)) die(`no such file: ${path}`);
     if (tty && !f["no-edit"]) edit(path);
     const to = typeof f.to === "string" ? f.to : undefined;
+    const follows = typeof f.follows === "string" ? f.follows : undefined;
     const { guide, url, synced, notified, path: saved } = await passalong
-      .share(readFileSync(path, "utf8"), { to })
+      .share(readFileSync(path, "utf8"), { to, follows })
       .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.parent) console.error(`follows ${guide.meta.parent}`);
     if (guide.meta.team)
       console.error(
         `handed to ${guide.meta.team}${guide.meta.to ? `/@${guide.meta.to}${notified ? " (emailed)" : " (in their inbox)"}` : " (team inbox)"}`,
@@ -334,16 +335,6 @@ const commands = {
     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) {
     const id = f._[0] || die("usage: passalong rm <id>");
     await passalong.remove(id).catch((e) => die(e.message));
@@ -392,7 +383,15 @@ const commands = {
     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)`);
+    // The server sends the state by name, because a number cannot tell "no ceiling" apart from
+    // "may sync nothing" — both of which arrive as a falsy limit.
+    const ceiling =
+      who.sync === "free"
+        ? ` (${who.limit} active on your plan)`
+        : who.sync === "none"
+          ? " (no plan — nothing is syncing)"
+          : " (no limit on your plan)";
+    console.log(`guides   ${who.guides} synced${ceiling}`);
     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>)"}`,
@@ -492,5 +491,11 @@ const commands = {
 
 const argv = flags(process.argv.slice(2));
 const cmd = argv._.shift() || "help";
-if (cmd === "--help" || cmd === "-h" || !commands[cmd]) commands.help();
+// The first thing anyone runs when something is off, and until now it printed the help page. The
+// parser only knows `--x`, so `--version` arrives as a flag on an empty command and `-v` as a word;
+// both are caught here, with `version`, before dispatch. Only the number goes to stdout, so
+// `passalong -v` can be read by a script comparing it against the registry.
+if (cmd === "-v" || cmd === "version" || (cmd === "help" && argv.version === true)) {
+  console.log(JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version);
+} else if (cmd === "--help" || cmd === "-h" || !commands[cmd]) commands.help();
 else await commands[cmd](argv).catch((e) => die(e.message));

package/package.json

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

@@ -33,6 +33,13 @@ session's history. Write for execution, not for permanence.
    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.
+
+   **If this session started from a passalong guide** — you ran `passalong start` or `pull` on an
+   id, or an agent opened one — and what you are capturing is what doing it taught you, add
+   `--follows <that id>`. The original then lists this one as a follow-up. That is the case when
+   you departed from it: changed or skipped a Step, adapted an `ASSUMES` for this stack, found the
+   fix a failing guide did not have, or hit a Gotcha it does not list. If it worked exactly as
+   written there is nothing to capture — say so with `passalong works <id>` instead.
 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

package/src/guide.js

@@ -5,16 +5,30 @@
 import { randomBytes } from "node:crypto";
 
 /**
- * A guide is a draft or it is published. `consumed` and `promoted` are legacy: they were an author
- * lifecycle laid over a transfer that already reports itself — `consumed` duplicated the verdict,
- * and `promoted` was a pull count with a name. Nothing sets them any more.
+ * A guide is a draft or it is published, and `consumed` is the author's shelf — off the board, out
+ * of the free tier's count, reversible. `promoted` is the one true legacy: an author lifecycle laid
+ * over a transfer that already reports itself, since a pull count says how travelled a guide is
+ * without anyone having to grade it.
  *
- * They stay in this list because they are *accepted*, not produced. The value lives in frontmatter
- * inside markdown files in other people's repositories, and `validate()` rejects a status it does
- * not know — so removing them here would make a guide shared a month ago fail to re-share today.
+ * This list is what is **accepted**, and it is not what may be **set** — that is `SETTABLE` below.
+ * The distinction is load-bearing. A status lives in frontmatter, inside markdown files in other
+ * people's repositories, and `validate()` rejects a status it does not know, so dropping a value
+ * from here would make a guide shared a month ago fail to re-share today.
  */
 export const STATUSES = ["draft", "published", "consumed", "promoted"];
 
+/**
+ * What a write may choose. `promoted` is absent: it cannot be set on a guide that does not already
+ * carry it, from any surface.
+ *
+ * Two reasons, and the second is the sharper one. A status that can still be set reads as a
+ * feature to whoever meets it next, however many deprecation notices sit around it. And
+ * `quota.ts` counts `published` and `promoted` as the statuses that occupy room — so while
+ * `promoted` remains settable, promoting every guide is an unlimited free tier. Closing the write
+ * closes that, and does it without touching what the free tier counts, which still has to include
+ * the guides already carrying the status.
+ */
+export const SETTABLE = ["draft", "published", "consumed"];
 /**
  * What a guide is for. The receiving agent behaves completely differently depending on the
  * answer, so it is a field rather than something inferred from the body.
@@ -291,6 +305,24 @@ export function sections(body) {
   return out;
 }
 
+/**
+ * Image targets no reader will ever load. Mirrors `unreachableImages` in apps/api/src/guide.ts,
+ * which is the authority and refuses the publish; this lets a local share fail before the network.
+ *
+ * Only a foreign scheme counts — `attachment://`, `blob:`, `file:`, `data:`. `https:` is left alone
+ * because embedding an image you host is legitimate, and a relative path is left alone because it
+ * has always been accepted.
+ */
+export function unreachableImages(markdown) {
+  const bad = [...String(markdown).matchAll(/!\[[^\]]*\]\(\s*([^)\s]+)/g)]
+    .map((m) => m[1].trim())
+    .filter((target) => {
+      const scheme = /^([a-z][a-z0-9+.\-]*):/i.exec(target);
+      return Boolean(scheme) && !/^https?$/i.test(scheme[1]);
+    });
+  return [...new Set(bad)];
+}
+
 /** Problems that make a guide unfit to publish. Empty array means it is fine. */
 export function validate({ meta, body }) {
   const errors = [];
@@ -321,6 +353,12 @@ export function validate({ meta, body }) {
     errors.push('a bug uses "## Reproduce", not "## Steps" — an agent executes Steps');
   }
   if (body.includes("<!-- passalong:")) errors.push("template placeholders are still in the body");
+  // An agent that has a file id but never called attach_screenshot writes the id as if it were a
+  // link. It publishes, and stores a guide whose screenshot was never uploaded anywhere.
+  for (const target of unreachableImages(body))
+    errors.push(
+      `${target} is not a URL a reader can load — attach the image first and use the URL it returns`,
+    );
   return errors;
 }
 
@@ -354,7 +392,26 @@ export function bugGuide({
   report = "",
   environment = "",
   status = "published",
+  evidence = [],
 } = {}) {
+  /**
+   * Screenshots, as markdown inside the document.
+   *
+   * They go under Problem rather than a heading of their own, because for a visual defect the
+   * picture *is* the problem statement and a bug's sections are a fixed set — a seventh heading
+   * would change the shape every reader keys on to add a line that already belongs in the first
+   * one.
+   *
+   * Naming them in the body is also the only thing that binds them: `claimShots` claims whatever
+   * the markdown points at, scoped to the author, so a URL listed anywhere else would upload
+   * evidence that no guide owns and the nightly sweep deletes.
+   */
+  const shots = (Array.isArray(evidence) ? evidence : [evidence])
+    .map((s) => String(s ?? "").trim())
+    .filter(Boolean)
+    // A caller that already has the markdown line from `attach_screenshot` passes it through
+    // whole; one holding just the URL gets it wrapped. Both reach the same document.
+    .map((s) => (s.startsWith("![") ? s : `![evidence](${s})`));
   const body = [
     // Written into the document, not added by whatever served it.
     //
@@ -367,10 +424,13 @@ export function bugGuide({
     "",
     "## Problem",
     problem.trim() || "_No description given._",
+  ];
+  if (shots.length) body.push("", ...shots);
+  body.push(
     "",
     "## Reproduce",
     reproduce.trim() || "_Not recorded — the description above is what there is._",
-  ];
+  );
   // Both are optional and both are worse than absent when empty: a Verification heading with
   // nothing under it says nobody knows what fixed looks like, on the section a fixer reads first.
   if (verification.trim()) body.push("", "## Verification", verification.trim());

package/src/mcp.js

@@ -81,6 +81,11 @@ export async function serve() {
         "because you reproduced it. " +
         "When you find defects you are not fixing — a test run, a QA pass, a review — call " +
         "file_bugs with all of them at once; each becomes a guide someone can take on its own. " +
+        "AN IMAGE THE USER SHOWED YOU IS EVIDENCE, NOT CONTEXT. Before filing or publishing, " +
+        "attach it with attach_screenshot and pass what it returns as `evidence` — a screenshot " +
+        "you described instead of attaching is the most useful thing in the report, thrown away. " +
+        "A guide already filed without one is not stuck: get_guide it, add the markdown line to " +
+        "the body, and publish_guide the same id — publishing claims whatever the markdown names. " +
         "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, team/@handle for one teammate, or " +
@@ -90,7 +95,13 @@ export async function serve() {
         "shows whether the guides they handed off have landed. When the user asks what they have " +
         "been working on, or wants a standup or a summary of a period, call log — but say that it " +
         "holds what they passed along and not everything they did. Gotchas are " +
-        "the highest-value section: record what failed and why.",
+        "the highest-value section: record what failed and why.\n" +
+        "A FOLLOW-UP IS A GUIDE, NOT A NOTE. When you worked from a guide and departed from it — " +
+        "changed or skipped a Step, adapted an ASSUMES for this stack, found the fix a failing " +
+        "guide did not have, or hit a Gotcha it does not list — publish what you learned as its " +
+        "own guide with publish_guide `parent` set to that guide's id; the original then lists it " +
+        "as a follow-up. If it worked exactly as written, do not: answer with verify_guide, or " +
+        "every guide collects copies that say nothing new.",
     },
   );
 
@@ -218,7 +229,10 @@ export async function serve() {
       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.",
+        "implemented, this says it actually works. A failing verdict must say what went wrong. " +
+        "If doing it taught you something the guide did not say — a flag it needed, a step that " +
+        "was wrong for this stack — publish that as its own guide with publish_guide `parent` set " +
+        "to this id. The author sees it as a follow-up; a verdict note is one line and gets lost.",
       inputSchema: {
         id: z.string().describe("passalong id"),
         ok: z.boolean().describe("true if the Verification steps passed"),
@@ -302,7 +316,8 @@ export async function serve() {
         const siblings = await related(meta);
         return text(
           `${lead}${r.markdown}${siblings}` +
-            `\n\n<!-- passalong: ${r.from}; written to ${r.path}; ${took} -->`,
+            `\n\n<!-- passalong: ${r.from}; written to ${r.path}; ${took} -->` +
+            `\n${passalong.followUpNote(meta)}`,
         );
       } catch (err) {
         return fail(err);
@@ -351,7 +366,8 @@ export async function serve() {
         return text(
           `${lead}${markdown}${siblings}` +
             `\n\n<!-- passalong: ${from}; written to ${path} -->` +
-            `\n${passalong.handoffNudge(meta)}`,
+            `\n${passalong.handoffNudge(meta)}` +
+            `\n${passalong.followUpNote(meta)}`,
         );
       } catch (err) {
         return fail(err);
@@ -394,7 +410,10 @@ export async function serve() {
       description:
         "Publish a guide from markdown (frontmatter + sections) — a transfer guide by default, or " +
         "a single bug with `kind: bug`; use file_bugs for more than one. Missing id, created, " +
-        'author, and source_context are filled in. `to` addresses it to a team ("khaime") or a ' +
+        "author, and source_context are filled in. A screenshot belongs in the markdown: attach it " +
+        "with attach_screenshot and put the line it returns in the body, because publishing claims " +
+        "whatever the markdown names. " +
+        '`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"),
@@ -406,13 +425,21 @@ export async function serve() {
           .string()
           .optional()
           .describe("directory the work happened in, used to infer source_context"),
+        parent: z
+          .string()
+          .optional()
+          .describe(
+            "id or share link of the guide this one came out of — set it when this is what you " +
+              "learned doing someone else's guide, so theirs lists it as a follow-up",
+          ),
       },
     },
-    async ({ markdown, to, cwd }) => {
+    async ({ markdown, to, cwd, parent }) => {
       try {
         const { guide, url, synced, notified, path } = await passalong.share(markdown, {
           cwd: cwd || process.cwd(),
           to,
+          follows: parent,
         });
         return json({
           id: guide.meta.id,
@@ -421,6 +448,7 @@ export async function serve() {
           synced,
           team: guide.meta.team || "",
           to: guide.meta.to || "",
+          parent: guide.meta.parent || "",
           notified,
           path,
         });
@@ -439,7 +467,10 @@ export async function serve() {
         "publishes each issue as its own guide — its own id, share link, and verdict — so a " +
         "reviewer can hand any one of them to whoever fixes it. Use this after a test run, a QA " +
         "pass, or a review that turned up defects; use publish_guide instead for work you " +
-        "finished and want repeated elsewhere. Needs sync (`passalong login`).",
+        "finished and want repeated elsewhere. If there is a screenshot of any of this, it is " +
+        "evidence: call attach_screenshot first and pass what it returns as that issue's " +
+        "`evidence`. Describing a screenshot instead of attaching it throws away the most useful " +
+        "thing in the report. Needs sync (`passalong login`).",
       inputSchema: {
         title: z
           .string()
@@ -456,6 +487,13 @@ export async function serve() {
         issues: z
           .array(
             z.object({
+              evidence: z
+                .array(z.string())
+                .default([])
+                .describe(
+                  "screenshot URLs from attach_screenshot, or the markdown lines it returned; " +
+                    "they go under Problem, where a reader looks first",
+                ),
               title: z.string().describe("what is broken, in one line"),
               problem: z
                 .string()
@@ -527,10 +565,11 @@ export async function serve() {
     {
       title: "Set guide status",
       description:
-        "Deprecated — prefer verify_guide. Marks a guide consumed or promoted, an author lifecycle " +
-        "nothing reads any more: the board reports where a transfer is and the verdict reports " +
-        "whether it worked. Kept so existing callers do not break. Only the author can promote.",
-      inputSchema: { id: z.string(), status: z.enum(["published", "consumed", "promoted"]) },
+        "Archive a guide (`consumed`) or put it back on the board (`published`). Archiving is the " +
+        "author's shelf: off the board, out of the free tier's count, reversible — it is not a " +
+        "judgement that the work landed, which is what verify_guide reports. `promoted` was " +
+        "retired and the server refuses it.",
+      inputSchema: { id: z.string(), status: z.enum(["published", "consumed"]) },
     },
     async ({ id, status }) => {
       try {

package/src/passalong.js

@@ -37,7 +37,7 @@ export function parseTarget(to) {
  * logged in. `to` addresses it: "team", "team/@handle", or "team/#group". Returns
  * { guide, path, url, synced }.
  */
-export async function share(markdown, { cwd = process.cwd(), to } = {}) {
+export async function share(markdown, { cwd = process.cwd(), to, follows } = {}) {
   const c = context(cwd);
   const raw = parse(markdown);
   let guide = stamp(
@@ -50,6 +50,10 @@ export async function share(markdown, { cwd = process.cwd(), to } = {}) {
   const target = parseTarget(to);
   if (target.team) guide.meta.team = target.team;
   if (target.to) guide.meta.to = target.to;
+  // `follows` names the guide this one came out of: an id, a share link, or a pulled .md file. An id
+  // is used as it is; a link or a file is read for the id in its own frontmatter. `validate()` below
+  // is what refuses a guide that names itself.
+  if (follows) guide.meta.parent = await resolveId(String(follows).trim());
   if (guide.meta.to && !guide.meta.team)
     throw new PassalongError("`to:` needs a team — address a handoff as team/handle");
   const errors = validate(guide);
@@ -292,6 +296,33 @@ export async function attach(file, { name = "" } = {}) {
   return { ...shot, markdown: `![${name || basename(file)}](${shot.url})` };
 }
 
+/**
+ * The line a guide arrives with, saying when what you do next deserves to be a guide of its own.
+ *
+ * Trailing, like the handoff nudge, so it never sits in front of the frontmatter. It is here and
+ * not only in the server's instructions because an agent reads the payload it is working from and
+ * skims everything else — the same reason the bug lead is inside the document.
+ *
+ * It says when *not* to as well. A follow-up for a guide that worked exactly as written is a copy
+ * that says nothing new, and a guide collecting those is worse than one with none; that answer is a
+ * verdict. For a bug the question is different — nothing to depart from, but a fix worth repeating
+ * elsewhere is a transfer guide, and the bug is where it came from.
+ */
+export function followUpNote(meta = {}) {
+  if (!meta.id) return "";
+  if (meta.kind === "bug")
+    return (
+      "<!-- passalong: once this is fixed, if the fix is worth repeating somewhere else, publish " +
+      `it as a transfer guide with publish_guide parent=${meta.id} so this bug lists it. -->`
+    );
+  return (
+    "<!-- passalong: if you depart from this guide — change or skip a Step, adapt an ASSUMES for " +
+    "this stack, find a fix it did not have, hit a Gotcha it does not list — publish what you " +
+    `learned as its own guide with publish_guide parent=${meta.id}. If it worked exactly as ` +
+    "written, answer with verify_guide instead. -->"
+  );
+}
+
 /** Local guides merged with synced ones (by id), newest first, optionally filtered. */
 export async function list(query = "", { remote = true, scope = "" } = {}) {
   const local = scope && scope !== "all" && scope !== "mine" ? [] : store.search(query);
@@ -390,7 +421,7 @@ export function summary(g) {
   };
 }
 
-/** Move a guide through its lifecycle: published → consumed → promoted (any order allowed). */
+/** Archive a guide (`consumed`) or put it back (`published`). The server refuses `promoted`. */
 export async function setStatus(id, status) {
   if (!STATUSES.includes(status))
     throw new PassalongError(`status must be one of ${STATUSES.join(", ")}`);