passalong 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# passalong
+
+Hand finished work to another context.
+
+Solve something non-trivial in one agent session. Run one command. Open a session in another
+repo, on another machine, or with a teammate, and the agent there already knows the whole story:
+the problem, the decisions and why, the steps, how to verify, and what went wrong along the way.
+
+```sh
+npm i -g passalong
+passalong setup      # installs the Claude Code capture skill + registers the MCP server
+passalong login      # optional: sync guides across machines and get share links
+```
+
+## The loop
+
+1. **Finish work** in Claude Code (or any agent). Say *"pass this along"*, run `/passalong-capture`, or
+   run `passalong share` yourself.
+2. **Trim and publish.** The draft opens in your editor. Save it and you get a short id and a link.
+3. **Pull on the other side.** `passalong pull <id>` in the target repo, or paste the link to any
+   agent with the Passalong MCP server. The guide lands in its context; it implements, adapting the
+   parts marked `ASSUMES:`.
+4. **Close.** `passalong done <id>` when it landed. `passalong promote <id>` if it keeps getting pulled.
+
+## 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 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 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 setup               install the Claude Code capture skill + register the MCP server
+passalong mcp                 run the MCP server over stdio
+```
+
+## 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`.
+
+## Guides are files
+
+Plain markdown with frontmatter in `~/.passalong/guides`. Yours to edit, grep, and commit.
+`passalong export` dumps everything. Works with no account; `passalong login` adds sync and share links.
+
+Point at a self-hosted server with `PASSALONG_API=https://your-host` before `passalong login`.

package/bin/passalong

@@ -0,0 +1,216 @@
+#!/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 pull <id|link>      fetch a guide into ./.passalong/ and print it
+//   passalong list [query]        your guides, 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 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 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";
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as api from "../src/api.js";
+import { scaffold } from "../src/capture.js";
+import { serialize } from "../src/guide.js";
+import * as passalong from "../src/passalong.js";
+import * as store from "../src/store.js";
+
+const PKG = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function flags(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t.startsWith("--")) {
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("-")) out[t.slice(2)] = true;
+      else out[t.slice(2)] = argv[++i];
+    } else out._.push(t);
+  }
+  return out;
+}
+
+function die(msg) {
+  console.error(`error: ${msg}`);
+  process.exit(1);
+}
+
+const tty = process.stdout.isTTY && process.stdin.isTTY;
+
+function edit(path) {
+  const editor = process.env.VISUAL || process.env.EDITOR || "vi";
+  const r = spawnSync(editor, [path], { stdio: "inherit", shell: true });
+  if (r.status !== 0) die(`${editor} exited with ${r.status}`);
+}
+
+function openInBrowser(url) {
+  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 < 30) return `${Math.floor(d)}d ago`;
+  return iso.slice(0, 10);
+}
+
+const commands = {
+  async share(f) {
+    let path = f._[0];
+    let fromDrafts = false;
+    if (!path) {
+      const [latest] = store.drafts();
+      if (latest) {
+        path = latest;
+        fromDrafts = true;
+        console.error(`using draft ${path}`);
+      } else {
+        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 (!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));
+    if (fromDrafts) store.removeDraft(path);
+    console.log(guide.meta.id);
+    console.error(`shared "${guide.meta.title}" → ${saved}`);
+    if (synced) console.error(`link: ${url}`);
+    else console.error("not synced (run `passalong login` to sync across machines)");
+  },
+
+  async pull(f) {
+    const ref = f._[0] || die("usage: passalong pull <id|link>");
+    const { markdown, path, from } = await passalong.pull(ref).catch((e) => die(e.message));
+    process.stdout.write(markdown);
+    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");
+    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}`);
+    }
+  },
+
+  async open(f) {
+    const id = f._[0] || die("usage: passalong open <id>");
+    const { guide } = await passalong.resolve(id).catch((e) => die(e.message));
+    if (guide.meta.url && tty && !f.print) {
+      openInBrowser(guide.meta.url);
+      console.error(guide.meta.url);
+    } else {
+      process.stdout.write(serialize(guide));
+      if (guide.meta.url) console.error(`\nlink: ${guide.meta.url}`);
+    }
+  },
+
+  async hub() {
+    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())}`;
+    if (tty) {
+      openInBrowser(url);
+      console.error(`${api.baseUrl()}/hub`);
+    } else console.log(url);
+  },
+
+  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`);
+  },
+
+  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`);
+  },
+
+  async rm(f) {
+    const id = f._[0] || die("usage: passalong rm <id>");
+    await passalong.remove(id).catch((e) => die(e.message));
+    console.error(`${id} removed`);
+  },
+
+  async export(f) {
+    const dir = resolve(f._[0] || "passalong-export");
+    const paths = passalong.exportAll(dir);
+    console.error(`exported ${paths.length} guide${paths.length === 1 ? "" : "s"} → ${dir}`);
+  },
+
+  async login(f) {
+    const given = f._[0];
+    if (given) {
+      store.writeConfig({ token: given, api: api.baseUrl() });
+      const who = await api.me().catch((e) => die(`token rejected: ${e.message}`));
+      console.error(`logged in (account ${who.account}) — ${api.baseUrl()}`);
+      return;
+    }
+    if (api.loggedIn() && !f.new) {
+      const who = await api.me().catch(() => null);
+      if (who) {
+        console.error(`already logged in (account ${who.account}). Attach another machine with:`);
+        console.error(`  passalong login ${api.token()}`);
+        return;
+      }
+    }
+    const { token, account } = await api.createAccount().catch((e) => die(e.message));
+    store.writeConfig({ token, api: api.baseUrl() });
+    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)");
+  },
+
+  async setup() {
+    const skillDir = join(homedir(), ".claude", "skills", "passalong-capture");
+    mkdirSync(skillDir, { recursive: true });
+    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" });
+      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`);
+    }
+    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() {
+    const { serve } = await import("../src/mcp.js");
+    await serve();
+  },
+
+  async help() {
+    const src = readFileSync(fileURLToPath(import.meta.url), "utf8");
+    const lines = src.split("\n").filter((l) => l.startsWith("//   passalong "));
+    console.log("passalong — hand finished work to another context\n");
+    console.log(lines.map((l) => l.slice(3)).join("\n"));
+  },
+};
+
+const argv = flags(process.argv.slice(2));
+const cmd = argv._.shift() || "help";
+if (cmd === "--help" || cmd === "-h" || !commands[cmd]) commands.help();
+else await commands[cmd](argv).catch((e) => die(e.message));

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "passalong",
+  "version": "0.1.0",
+  "description": "Hand a finished implementation from one context to another, in a form an AI agent can act on.",
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "agent",
+    "handoff",
+    "knowledge-transfer",
+    "cli",
+    "markdown"
+  ],
+  "homepage": "https://passalong.kreativekorna.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codellyson/passalong.git",
+    "directory": "packages/passalong"
+  },
+  "author": "Lukman Isiaka",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "passalong": "bin/passalong"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skill"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.24.0"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: passalong-capture
+description: Distill what was just accomplished in this session into a Passalong transfer guide and publish it, so another repo, machine, agent session, or teammate can implement the same thing. Use when the user says "pass this along", "passalong this", "hand this off", "share this with <repo/person>", "capture this for later", "write a transfer guide", or runs /passalong-capture.
+---
+
+# Passalong capture
+
+You are turning this session into a **transfer guide**: executable context for an agent in a
+different place. The reader is an AI agent (with a developer watching) that has none of this
+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,
+   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
+   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
+   `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:
+
+   ```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 `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.
+
+## Guide structure
+
+```markdown
+---
+title: <what this accomplishes, as a verb phrase: "Add Paystack webhook verification">
+author: <git user.name, if known>
+source_context: <repo or product this came from>
+status: published
+stack_assumptions: [<runtime/framework/db/service versions the steps depend on>]
+tags: [<3 to 6 lowercase keywords>]
+---
+
+## Problem
+What was broken or needed. Two or three sentences. Include the observable symptom.
+
+## Solution shape
+The approach at a high level, before any code. One short paragraph.
+
+## Decisions and rationale
+- **Chose X over Y** because Z. (Each real decision, with what was rejected.)
+
+## Steps
+1. ASSUMES: <stack>. If <other>, <adjust>. Then the concrete step, with the file path and the code or command.
+2. ...
+
+## Verification
+Commands to run and what they should print. Test cases. What "done" looks like.
+
+## Gotchas
+- What failed along the way, the exact error, and why. What looked right but wasn't.
+```
+
+## 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.
+- **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

@@ -0,0 +1,80 @@
+// 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.
+import { readConfig } from "./store.js";
+
+export const DEFAULT_API = "https://passalong.kreativekorna.com";
+
+export class ApiError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+}
+
+export function baseUrl() {
+  return (process.env.PASSALONG_API || readConfig().api || DEFAULT_API).replace(/\/$/, "");
+}
+
+export function token() {
+  return process.env.PASSALONG_TOKEN || readConfig().token || null;
+}
+
+export function loggedIn() {
+  return Boolean(token());
+}
+
+async function call(path, { method = "GET", body, auth = true, raw = false } = {}) {
+  const headers = {};
+  if (auth) {
+    const t = token();
+    if (!t) throw new ApiError(401, "not logged in — run `passalong login` to enable sync");
+    headers.authorization = `Bearer ${t}`;
+  }
+  if (body !== undefined) {
+    headers["content-type"] = typeof body === "string" ? "text/markdown" : "application/json";
+  }
+  let res;
+  try {
+    res = await fetch(`${baseUrl()}${path}`, {
+      method,
+      headers,
+      body: body === undefined ? undefined : typeof body === "string" ? body : JSON.stringify(body),
+    });
+  } catch (err) {
+    throw new ApiError(0, `could not reach ${baseUrl()} (${err.message})`);
+  }
+  if (!res.ok) {
+    const text = await res.text();
+    let message = text;
+    try {
+      message = JSON.parse(text).message || text;
+    } catch {}
+    throw new ApiError(res.status, message || res.statusText);
+  }
+  return raw ? res.text() : res.json();
+}
+
+/** 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 publish = (id, markdown) =>
+  call(`/v1/guides/${id}`, { method: "PUT", body: markdown });
+export const list = (q = "") => call(`/v1/guides${q ? `?q=${encodeURIComponent(q)}` : ""}`);
+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" });
+
+/** 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);
+  if (!u.pathname.endsWith(".md")) u.pathname = `${u.pathname.replace(/\/$/, "")}.md`;
+  const res = await fetch(u);
+  if (!res.ok)
+    throw new ApiError(res.status, `could not fetch ${url}: ${res.status} ${res.statusText}`);
+  return res.text();
+}
+
+export function shareUrl(id, key) {
+  return `${baseUrl()}/g/${id}/${key}`;
+}

package/src/capture.js

@@ -0,0 +1,56 @@
+// Fallback capture when no agent wrote a draft: scaffold one from the working directory so the
+// developer starts from "what changed" instead of a blank page. The Claude Code skill in
+// skills/passalong-capture does the real distillation from a session transcript.
+import { execFileSync } from "node:child_process";
+import { basename } from "node:path";
+import { template } from "./guide.js";
+
+function git(cwd, ...args) {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf8",
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/** What we can infer about the current context without reading any session. */
+export function context(cwd = process.cwd()) {
+  const root = git(cwd, "rev-parse", "--show-toplevel");
+  const name = basename(root || cwd);
+  const branch = root ? git(cwd, "rev-parse", "--abbrev-ref", "HEAD") : "";
+  const author = git(cwd, "config", "user.name");
+  const commits = root ? git(cwd, "log", "--oneline", "-8").split("\n").filter(Boolean) : [];
+  const changed = root
+    ? git(cwd, "diff", "--stat", "HEAD~5..HEAD").split("\n").filter(Boolean).slice(-1)[0] || ""
+    : "";
+  const files = root
+    ? git(cwd, "diff", "--name-only", "HEAD~5..HEAD").split("\n").filter(Boolean)
+    : [];
+  return { root, name, branch, author, commits, changed, files };
+}
+
+/** A draft pre-filled with repo facts. Recent activity is appended as a comment for reference. */
+export function scaffold(cwd = process.cwd()) {
+  const c = context(cwd);
+  let md = template({
+    title: "",
+    author: c.author,
+    source_context: c.branch && c.branch !== "HEAD" ? `${c.name}@${c.branch}` : c.name,
+  });
+  if (c.commits.length) {
+    md += [
+      "",
+      "<!-- passalong: recent activity in this repo, for reference while you write. Delete when done.",
+      ...c.commits.map((l) => `  ${l}`),
+      c.changed ? `  ${c.changed}` : "",
+      ...c.files.slice(0, 30).map((f) => `  ${f}`),
+      "-->",
+      "",
+    ].join("\n");
+  }
+  return md;
+}

package/src/guide.js

@@ -0,0 +1,209 @@
+// The transfer guide format: plain markdown with a small YAML-ish frontmatter block.
+//
+// No proprietary format and no YAML library. The frontmatter only ever holds strings and
+// lists of strings, so a deliberately tiny parser covers it and stays readable when hand-edited.
+import { randomBytes } from "node:crypto";
+
+export const STATUSES = ["draft", "published", "consumed", "promoted"];
+
+// Body sections in the order a guide should present them. The heading text is what the
+// receiving agent keys on, so keep these stable.
+export const SECTIONS = [
+  "Problem",
+  "Solution shape",
+  "Decisions and rationale",
+  "Steps",
+  "Verification",
+  "Gotchas",
+];
+
+// Fields that hold a list of strings. Everything else is a plain string.
+const LIST_FIELDS = new Set(["stack_assumptions", "tags"]);
+
+// IDs are short enough to type and say out loud. 8 chars from a 31-letter alphabet with the
+// look-alikes removed (0/o, 1/l/i) is ~40 bits: plenty for addressing, not a secret.
+const ID_ALPHABET = "abcdefghjkmnpqrstuvwxyz23456789";
+export function newId(length = 8) {
+  const bytes = randomBytes(length);
+  let out = "";
+  for (let i = 0; i < length; i++) out += ID_ALPHABET[bytes[i] % ID_ALPHABET.length];
+  return out;
+}
+export const ID_RE = /^[a-z0-9]{6,12}$/;
+
+function scalar(raw) {
+  const v = raw.trim();
+  if (v === "") return "";
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    return v.slice(1, -1).replace(/\\"/g, '"');
+  }
+  return v;
+}
+
+function inlineList(raw) {
+  const inner = raw.trim().slice(1, -1).trim();
+  if (inner === "") return [];
+  return inner
+    .split(",")
+    .map(scalar)
+    .filter((s) => s !== "");
+}
+
+/** Parse a frontmatter block (the text between the --- fences) into an object. */
+export function parseFrontmatter(text) {
+  const meta = {};
+  const lines = text.split(/\r?\n/);
+  let listKey = null;
+  for (const line of lines) {
+    if (line.trim() === "" || line.trim().startsWith("#")) continue;
+    const item = /^\s+-\s*(.*)$/.exec(line);
+    if (item && listKey) {
+      meta[listKey].push(scalar(item[1]));
+      continue;
+    }
+    const kv = /^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/.exec(line);
+    if (!kv) continue;
+    const [, key, rest] = kv;
+    if (rest.trim() === "" && LIST_FIELDS.has(key)) {
+      meta[key] = [];
+      listKey = key;
+    } else if (rest.trim().startsWith("[") && rest.trim().endsWith("]")) {
+      meta[key] = inlineList(rest);
+      listKey = null;
+    } else {
+      meta[key] = LIST_FIELDS.has(key) ? [scalar(rest)] : scalar(rest);
+      listKey = null;
+    }
+  }
+  for (const k of LIST_FIELDS) if (meta[k] === undefined) meta[k] = [];
+  return meta;
+}
+
+function quote(v) {
+  const s = String(v ?? "");
+  // Quote anything YAML would misread: colons, leading symbols, or empty.
+  return /[:#[\]{}"'|>&*!%@`,]|^\s|\s$|^$/.test(s) ? `"${s.replace(/"/g, '\\"')}"` : s;
+}
+
+const META_ORDER = [
+  "id",
+  "title",
+  "created",
+  "author",
+  "source_context",
+  "status",
+  "stack_assumptions",
+  "tags",
+];
+
+export function serializeFrontmatter(meta) {
+  const keys = [
+    ...META_ORDER.filter((k) => k in meta),
+    ...Object.keys(meta).filter((k) => !META_ORDER.includes(k)),
+  ];
+  const out = [];
+  for (const key of keys) {
+    const v = meta[key];
+    if (Array.isArray(v)) {
+      out.push(v.length ? `${key}: [${v.map(quote).join(", ")}]` : `${key}: []`);
+    } else {
+      out.push(`${key}: ${quote(v)}`);
+    }
+  }
+  return out.join("\n");
+}
+
+/** Split a markdown document into { meta, body }. A document with no frontmatter has empty meta. */
+export function parse(markdown) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(markdown);
+  if (!m) return { meta: parseFrontmatter(""), body: markdown.trim() };
+  return { meta: parseFrontmatter(m[1]), body: m[2].trim() };
+}
+
+export function serialize({ meta, body }) {
+  return `---\n${serializeFrontmatter(meta)}\n---\n\n${body.trim()}\n`;
+}
+
+/** Map of "## Heading" → section text, so callers can look at Verification or Gotchas alone. */
+export function sections(body) {
+  const out = {};
+  let current = null;
+  for (const line of body.split(/\r?\n/)) {
+    const h = /^##\s+(.+?)\s*$/.exec(line);
+    if (h) {
+      current = h[1];
+      out[current] = "";
+      continue;
+    }
+    if (current) out[current] += `${line}\n`;
+  }
+  for (const k of Object.keys(out)) out[k] = out[k].trim();
+  return out;
+}
+
+/** Problems that make a guide unfit to publish. Empty array means it is fine. */
+export function validate({ meta, body }) {
+  const errors = [];
+  if (!meta.title) errors.push("frontmatter needs a title");
+  if (meta.id && !ID_RE.test(meta.id)) errors.push(`id "${meta.id}" is not a valid passalong id`);
+  if (meta.status && !STATUSES.includes(meta.status)) {
+    errors.push(`status must be one of ${STATUSES.join(", ")}`);
+  }
+  const have = sections(body);
+  for (const s of ["Problem", "Steps"]) {
+    if (!have[s]) errors.push(`missing "## ${s}" section`);
+  }
+  if (body.includes("<!-- passalong:")) errors.push("template placeholders are still in the body");
+  return errors;
+}
+
+/** Fill in what a fresh guide needs before it can be stored. Returns a new object. */
+export function stamp(guide, defaults = {}) {
+  const meta = { ...guide.meta };
+  if (!meta.id) meta.id = newId();
+  if (!meta.created) meta.created = new Date().toISOString();
+  if (!meta.status) meta.status = "draft";
+  for (const [k, v] of Object.entries(defaults))
+    if (meta[k] === undefined || meta[k] === "") meta[k] = v;
+  return { meta, body: guide.body };
+}
+
+/** A draft with the section skeleton. Placeholders are HTML comments so they vanish when rendered. */
+export function template(meta = {}) {
+  const body = [
+    "## Problem",
+    "<!-- passalong: What was broken or needed, in two or three sentences. -->",
+    "",
+    "## Solution shape",
+    "<!-- passalong: The approach at a high level, before any code. -->",
+    "",
+    "## Decisions and rationale",
+    "<!-- passalong: What was chosen, what was rejected, and why. This lets the receiver adapt instead of copy. -->",
+    "",
+    "## Steps",
+    "<!-- passalong: Concrete implementation steps. Mark context-specific parts: ASSUMES: Postgres. If MySQL, adjust X. -->",
+    "",
+    "## Verification",
+    "<!-- passalong: Commands, expected outputs, test cases that prove it worked. -->",
+    "",
+    "## Gotchas",
+    "<!-- passalong: What failed along the way and why. Often the highest-value section. -->",
+  ].join("\n");
+  return serialize({
+    meta: {
+      title: "",
+      author: "",
+      source_context: "",
+      status: "draft",
+      stack_assumptions: [],
+      tags: [],
+      ...meta,
+    },
+    body,
+  });
+}
+
+/** Strip the template comments so an untouched section reads as empty rather than as a prompt. */
+export function stripPlaceholders(body) {
+  return body.replace(/^<!-- passalong:.*?-->\n?/gm, "").trim();
+}

package/src/mcp.js

@@ -0,0 +1,130 @@
+// 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.
+//
+//   claude mcp add passalong -- passalong mcp
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { SECTIONS, template } from "./guide.js";
+import * as passalong from "./passalong.js";
+
+const text = (s) => ({ content: [{ type: "text", text: s }] });
+const json = (data) => text(JSON.stringify(data, null, 2));
+const fail = (err) => ({ content: [{ type: "text", text: err.message }], isError: true });
+
+export async function serve() {
+  const server = new McpServer(
+    { name: "passalong", version: "0.1.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.",
+    },
+  );
+
+  server.registerTool(
+    "search_guides",
+    {
+      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("") },
+    },
+    async ({ query }) => {
+      try {
+        const rows = await passalong.list(query);
+        return json({ guides: rows, warning: rows.warning });
+      } 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.",
+      inputSchema: {
+        ref: z.string().describe("passalong id (e.g. k3mq2xa7) or share URL"),
+        cwd: z
+          .string()
+          .optional()
+          .describe("directory to write .passalong/<id>.md into; default is the server's cwd"),
+      },
+    },
+    async ({ ref, cwd }) => {
+      try {
+        const { markdown, path, from } = await passalong.pull(ref, { cwd: cwd || process.cwd() });
+        return text(`${markdown}\n\n<!-- passalong: ${from}; written to ${path} -->`);
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "publish_guide",
+    {
+      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.",
+      inputSchema: {
+        markdown: z.string().describe("full guide markdown; start from guide_template"),
+        cwd: z
+          .string()
+          .optional()
+          .describe("directory the work happened in, used to infer source_context"),
+      },
+    },
+    async ({ markdown, cwd }) => {
+      try {
+        const { guide, url, synced, path } = await passalong.share(markdown, {
+          cwd: cwd || process.cwd(),
+        });
+        return json({ id: guide.meta.id, title: guide.meta.title, url, synced, path });
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "guide_template",
+    {
+      title: "Guide template",
+      description: "The empty transfer guide skeleton with guidance comments for each section.",
+      inputSchema: {},
+    },
+    async () => text(template()),
+  );
+
+  server.registerTool(
+    "set_guide_status",
+    {
+      title: "Set guide status",
+      description:
+        "Mark a guide consumed (implemented on the receiving side) or promoted (a reusable reference).",
+      inputSchema: { id: z.string(), status: z.enum(["published", "consumed", "promoted"]) },
+    },
+    async ({ id, status }) => {
+      try {
+        const g = await passalong.setStatus(id, status);
+        return json(passalong.summary(g));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  await server.connect(new StdioServerTransport());
+}

package/src/passalong.js

@@ -0,0 +1,157 @@
+// 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";
+import { join } from "node:path";
+import * as api from "./api.js";
+import { context } from "./capture.js";
+import { ID_RE, parse, STATUSES, serialize, stamp, stripPlaceholders, validate } from "./guide.js";
+import * as store from "./store.js";
+
+export class PassalongError extends Error {}
+
+/**
+ * Publish a guide from markdown: fill in defaults, validate, store locally, and sync when
+ * logged in. Returns { guide, path, url, synced }.
+ */
+export async function share(markdown, { cwd = process.cwd() } = {}) {
+  const c = context(cwd);
+  const raw = parse(markdown);
+  let guide = stamp(
+    { meta: raw.meta, body: stripPlaceholders(raw.body) },
+    {
+      author: c.author,
+      source_context: c.branch && c.branch !== "HEAD" ? `${c.name}@${c.branch}` : c.name,
+    },
+  );
+  const errors = validate(guide);
+  if (errors.length)
+    throw new PassalongError(`guide is not ready to share:\n  - ${errors.join("\n  - ")}`);
+  if (guide.meta.status === "draft")
+    guide = { ...guide, meta: { ...guide.meta, status: "published" } };
+
+  let url = guide.meta.url || null;
+  let synced = false;
+  if (api.loggedIn()) {
+    const res = await api.publish(guide.meta.id, serialize(guide));
+    url = res.url;
+    synced = true;
+    guide = { ...guide, meta: { ...guide.meta, url } };
+  }
+  const path = store.save(guide);
+  return { guide, path, url, synced };
+}
+
+/** Resolve a reference (id, share URL, or local file path) to a guide. */
+export async function resolve(ref) {
+  if (/^https?:\/\//.test(ref)) {
+    const md = await api.fetchShared(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))
+    throw new PassalongError(`"${ref}" is not a passalong id, share link, or .md file`);
+  const local = store.get(ref);
+  if (local) return { guide: local, from: "local" };
+  if (api.loggedIn()) {
+    try {
+      const md = await api.get(ref);
+      const guide = parse(md);
+      store.save(guide); // cache so the next pull is offline
+      return { guide, from: "sync" };
+    } catch (err) {
+      if (err.status !== 404) throw err;
+    }
+  }
+  throw new PassalongError(
+    `no guide "${ref}" (not local${api.loggedIn() ? " or synced" : "; not logged in, so sync was not checked"})`,
+  );
+}
+
+/**
+ * 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.
+ */
+export async function pull(ref, { cwd = process.cwd(), write = true } = {}) {
+  const { guide, from } = await resolve(ref);
+  let path = null;
+  if (write) {
+    const dir = join(cwd, ".passalong");
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    path = join(dir, `${guide.meta.id}.md`);
+    writeFileSync(path, serialize(guide));
+  }
+  return { guide, from, path, markdown: serialize(guide) };
+}
+
+/** Local guides merged with synced ones (by id), newest first, optionally filtered. */
+export async function list(query = "", { remote = true } = {}) {
+  const local = 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);
+      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" });
+      }
+    } catch (err) {
+      rows.warning = `sync unavailable: ${err.message}`;
+    }
+  }
+  return rows.sort((a, b) => (b.created || "").localeCompare(a.created || ""));
+}
+
+export function summary(g) {
+  return {
+    id: g.meta.id,
+    title: g.meta.title,
+    status: g.meta.status,
+    created: g.meta.created,
+    source_context: g.meta.source_context,
+    tags: g.meta.tags || [],
+    stack_assumptions: g.meta.stack_assumptions || [],
+    url: g.meta.url || null,
+  };
+}
+
+/** Move a guide through its lifecycle: published → consumed → promoted (any order allowed). */
+export async function setStatus(id, status) {
+  if (!STATUSES.includes(status))
+    throw new PassalongError(`status must be one of ${STATUSES.join(", ")}`);
+  const { guide } = await resolve(id);
+  const next = { ...guide, meta: { ...guide.meta, status } };
+  store.save(next);
+  if (api.loggedIn() && guide.meta.url) await api.setStatus(id, status);
+  return next;
+}
+
+export async function remove(id) {
+  store.remove(id);
+  if (api.loggedIn()) {
+    try {
+      await api.remove(id);
+    } catch (err) {
+      if (err.status !== 404) throw err;
+    }
+  }
+}
+
+/** Write every local guide to a directory as plain markdown. Returns the paths written. */
+export function exportAll(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const paths = [];
+  for (const g of store.list()) {
+    const p = join(dir, `${g.meta.id}.md`);
+    writeFileSync(p, serialize(g));
+    paths.push(p);
+  }
+  return paths;
+}

package/src/store.js

@@ -0,0 +1,113 @@
+// The local store: ~/.passalong (override with PASSALONG_HOME). Guides are one markdown file each so
+// the whole thing is greppable, git-friendly, and there is nothing to export that isn't
+// already a file you own.
+//
+//   ~/.passalong/config.json   api url + token
+//   ~/.passalong/guides/<id>.md
+//   ~/.passalong/drafts/*.md   captured but not yet shared
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parse, serialize } from "./guide.js";
+
+export const HOME = process.env.PASSALONG_HOME || join(homedir(), ".passalong");
+export const GUIDES = join(HOME, "guides");
+export const DRAFTS = join(HOME, "drafts");
+const CONFIG = join(HOME, "config.json");
+
+function ensure() {
+  for (const d of [HOME, GUIDES, DRAFTS])
+    if (!existsSync(d)) mkdirSync(d, { recursive: true, mode: 0o700 });
+}
+
+export function readConfig() {
+  if (!existsSync(CONFIG)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(patch) {
+  ensure();
+  const next = { ...readConfig(), ...patch };
+  writeFileSync(CONFIG, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  return next;
+}
+
+export function guidePath(id) {
+  return join(GUIDES, `${id}.md`);
+}
+
+export function get(id) {
+  const p = guidePath(id);
+  if (!existsSync(p)) return null;
+  return parse(readFileSync(p, "utf8"));
+}
+
+export function save(guide) {
+  ensure();
+  writeFileSync(guidePath(guide.meta.id), serialize(guide));
+  return guidePath(guide.meta.id);
+}
+
+export function remove(id) {
+  const p = guidePath(id);
+  if (existsSync(p)) unlinkSync(p);
+}
+
+/** All local guides, newest first. */
+export function list() {
+  ensure();
+  return readdirSync(GUIDES)
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => parse(readFileSync(join(GUIDES, f), "utf8")))
+    .filter((g) => g.meta.id)
+    .sort((a, b) => (b.meta.created || "").localeCompare(a.meta.created || ""));
+}
+
+/** Draft files, newest first. */
+export function drafts() {
+  ensure();
+  return readdirSync(DRAFTS)
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => join(DRAFTS, f))
+    .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+}
+
+export function draftPath(name) {
+  ensure();
+  return join(DRAFTS, `${name}.md`);
+}
+
+export function removeDraft(path) {
+  if (path.startsWith(DRAFTS) && existsSync(path)) unlinkSync(path);
+}
+
+/** Case-insensitive match on title, tags, source context, and body. */
+export function search(query, guides = list()) {
+  const q = query.trim().toLowerCase();
+  if (!q) return guides;
+  const terms = q.split(/\s+/);
+  return guides.filter((g) => {
+    const hay = [
+      g.meta.title,
+      g.meta.source_context,
+      ...(g.meta.tags || []),
+      ...(g.meta.stack_assumptions || []),
+      g.body,
+    ]
+      .join("\n")
+      .toLowerCase();
+    return terms.every((t) => hay.includes(t));
+  });
+}