passalong 0.5.0 → 0.8.0

package/README.md

@@ -35,11 +35,11 @@ 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>           deprecated: mark consumed
+passalong archive <id>        off your board and out of the free tier's count (was `done`)
 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
+passalong login [token]       sign in with your email and password, or attach this machine with a token
 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)

package/bin/passalong

@@ -25,12 +25,20 @@
 //   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 assign <id> <to>    give it to @handle, a #group, or "team" — yours, or assigned to you
+//   passalong admin create <email>   make an account that runs Passalong (owner only)
+//   passalong admin list          who runs it
+//   passalong admin grant|revoke <@handle>   make an existing account an admin, or stop it being one
+//   passalong gift <who> --until <date> [--why "..."] [--seats N]
+//                                 give Solo to @handle, or Team to team/slug, until a date (operator only)
+//   passalong gifts               what has been given away, and what is still running
+//   passalong ungift <gift id>    take one back now
 //   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 archive <id>        off your board and out of the free tier's count (was `done`)
 //   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
+//   passalong login [token]       sign in with your email and password, or attach this machine with a token
 //   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)
@@ -41,9 +49,10 @@
 //   passalong now                 what this worktree holds and what is waiting (the hooks call --hook)
 //   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 { execFileSync, spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import * as api from "../src/api.js";
@@ -74,6 +83,38 @@ function die(msg) {
 
 const tty = process.stdout.isTTY && process.stdin.isTTY;
 
+/**
+ * One line typed at the terminal. `hidden` turns the echo off, so a password does not end up in a
+ * screen share, a scrollback or somebody's terminal recording.
+ *
+ * Written against readline rather than a dependency because this package has none beyond the MCP
+ * SDK and zod, and asking for a line of text is not where that changes.
+ */
+async function ask(question, { hidden = false } = {}) {
+  const { createInterface } = await import("node:readline");
+  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+  if (hidden) {
+    // readline still writes the prompt itself; everything after it is swallowed. The newline the
+    // user's Return would have echoed is put back by hand, or the next line starts mid-prompt.
+    rl.output.write(question);
+    rl._writeToOutput = () => {};
+  }
+  try {
+    // `close` as well as an answer: stdin reaching EOF part-way through — a pipe, a closed pty, a
+    // ^D — never calls the question's callback, and without this the promise is simply never
+    // settled and the process exits on a warning about it rather than saying what happened.
+    const answer = await new Promise((done) => {
+      rl.on("close", () => done(null));
+      rl.question(hidden ? "" : question, done);
+    });
+    if (hidden) process.stdout.write("\n");
+    if (answer === null) die("nothing to read from — sign in at the terminal, or pass a token");
+    return answer.trim();
+  } finally {
+    rl.close();
+  }
+}
+
 function edit(path) {
   const editor = process.env.VISUAL || process.env.EDITOR || "vi";
   const r = spawnSync(editor, [path], { stdio: "inherit", shell: true });
@@ -130,6 +171,53 @@ const MONTHS = "January February March April May June July August September Octo
 /** "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)}`;
 
+// ---- the status line cache --------------------------------------------------------------------------
+
+/** One small file per working directory, so two sessions in two repos each see their own. */
+const statusPath = (cwd) =>
+  join(store.HOME, "statusline", `${createHash("sha1").update(cwd).digest("hex").slice(0, 16)}.json`);
+
+function writeStatus(cwd, text) {
+  const p = statusPath(cwd);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify({ at: Date.now(), text }));
+}
+
+/** How old a cached line may be before a refresh is started behind it. */
+const STATUS_TTL_MS = 30_000;
+
+/**
+ * Print the cached line for this directory at once, and when it is stale start a detached refresh
+ * that writes the next one. The first run in a directory prints a placeholder; the refresh lands
+ * within a second or two, and the next update shows it. Offline or signed out, it says nothing.
+ */
+async function statusLine() {
+  let input = {};
+  if (!process.stdin.isTTY) {
+    let raw = "";
+    for await (const chunk of process.stdin) raw += chunk;
+    try {
+      input = JSON.parse(raw || "{}");
+    } catch {}
+  }
+  if (!api.loggedIn()) return;
+  const cwd = input.workspace?.current_dir || input.cwd || process.cwd();
+  let cached = null;
+  try {
+    cached = JSON.parse(readFileSync(statusPath(cwd), "utf8"));
+  } catch {}
+  process.stdout.write(cached?.text ?? "passalong");
+  if (!cached || Date.now() - cached.at > STATUS_TTL_MS) {
+    // Marked fresh before the refresh starts, so a burst of updates starts one refresh, not ten.
+    writeStatus(cwd, cached?.text ?? "passalong");
+    spawn(process.execPath, [fileURLToPath(import.meta.url), "now", "--statusline-refresh", cwd], {
+      detached: true,
+      stdio: "ignore",
+      env: process.env,
+    }).unref();
+  }
+}
+
 const commands = {
   async share(f) {
     let path = f._[0];
@@ -430,6 +518,86 @@ const commands = {
     console.error(`${r.id} handed back — the author has been told: "${r.note}"`);
   },
 
+  async assign(f) {
+    const id = f._[0] || die('usage: passalong assign <id> <@handle | #group | team>');
+    const to = f._[1] || die('say who: @handle for one person, #group, or "team" for everyone');
+    const r = await passalong.assign(id, to).catch((e) => die(e.message));
+    const back = r.taken_back ? ` — taken back from ${r.taken_back} who had it, and they were told` : "";
+    console.error(`${r.id} is now for ${r.to || "everyone in the team"}${back}`);
+  },
+
+  // ---- who runs the product ---------------------------------------------------------------
+  // `passalong admin <create|list|grant|revoke>`. An admin signs in like anybody else: the role is
+  // a column, so there is no admin password and no admin token — only an account that has it.
+  // "admin" is the word everywhere a person reads; `super` stays the stored value.
+
+  async admin(f) {
+    const what = f._[0] || "list";
+    if (what === "create") {
+      const email = f._[1] || die("usage: passalong admin create <email>");
+      const r = await api.makeAdmin(email).catch((e) => die(e.message));
+      // Shown once, and only here. The link is a day long because it is handed to somebody
+      // rather than clicked on the spot.
+      // Three labelled values on stdout, so one can be cut out with awk. "password link", not
+      // "password": the value is a URL, and somebody will try to paste it into a password field.
+      console.log(`account        ${r.account}`);
+      console.log(`token          ${r.token}`);
+      console.log(`password link  ${r.password_url}`);
+      console.error(
+        `\n${r.email} is an admin. The token is for \`passalong login\`, the link sets their ` +
+          `password for the hub, and it expires ${r.expires.slice(0, 10)}. Neither is shown again.`,
+      );
+      return;
+    }
+    if (what === "grant" || what === "revoke") {
+      const who = f._[1] || die(`usage: passalong admin ${what} <@handle | account id>`);
+      const call = what === "grant" ? api.grantAdmin : api.revokeAdmin;
+      const r = await call(who).catch((e) => die(e.message));
+      console.error(
+        what === "grant" ? `${r.name} is now an admin` : `${r.name} is no longer an admin`,
+      );
+      return;
+    }
+    if (what !== "list") die("usage: passalong admin <create <email> | list | grant | revoke>");
+    const { supers = [] } = await api.listAdmins().catch((e) => die(e.message));
+    if (!supers.length) return console.error("nobody is an admin yet");
+    for (const s of supers)
+      console.log(`${s.id}  ${s.name}${s.email ? `  ${s.email}` : ""}  since ${s.since.slice(0, 10)}`);
+  },
+
+  // ---- giving a plan away -----------------------------------------------------------------
+  // Only for whoever the deployment names in ADMIN_ACCOUNTS; for everybody else the routes behind
+  // these are 404, and the message says so rather than pretending the command does not exist.
+
+  async gift(f) {
+    const to = f._[0] || die('usage: passalong gift <@handle | team/slug> --until 2027-09-23 [--why "..."]');
+    const until = f.until || die("say when it ends: --until 2027-09-23. A gift with no end is a price change");
+    const r = await api
+      .giveGift({ to, until, why: f.why || "", seats: Number(f.seats || 0) })
+      .catch((e) => die(e.message));
+    // The seat count is said back whether or not it was asked for: left off, it is the number of
+    // members the team has today, and an operator should read which number that turned out to be.
+    const seats = r.kind === "team" ? ` for ${r.seats} seat${r.seats === 1 ? "" : "s"}` : "";
+    console.error(`${r.to} is on ${r.plan}${seats} until ${r.until.slice(0, 10)} — gift ${r.id}`);
+  },
+
+  async gifts() {
+    const { gifts = [] } = await api.listGifts().catch((e) => die(e.message));
+    if (!gifts.length) return console.error("no plans given away yet");
+    for (const g of gifts) {
+      const state = g.live ? `until ${g.until.slice(0, 10)}` : "over";
+      console.log(
+        `${g.id}  ${g.plan.padEnd(5)} ${state.padEnd(16)} ${g.to}${g.why ? ` — ${g.why}` : ""}`,
+      );
+    }
+  },
+
+  async ungift(f) {
+    const id = f._[0] || die("usage: passalong ungift <gift id>  (passalong gifts lists them)");
+    await api.takeGiftBack(id).catch((e) => die(e.message));
+    console.error(`${id} taken back — that plan is lapsed as of now`);
+  },
+
   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));
@@ -447,16 +615,29 @@ const commands = {
   /**
    * 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.
+   * The command was `done`, and the status it sets is still `consumed`, because both once meant "I
+   * implemented it". That meaning went to the verdict, where it belongs — it is the reader's
+   * judgement, not the author's — and what was left is shelf space, which has a job nothing else
+   * does: the only way under the sync limit that does not delete the work, and the 402 says so by
+   * name. So the command says what it does now.
+   *
+   * `consumed` stays on disk. It is a status inside markdown files in other people's
+   * repositories, and `validate()` refuses a status it does not know, so renaming the value would
+   * make a guide shared a month ago fail to re-share today. The word people read and the token the
+   * format stores are allowed to differ; what is not allowed is two words for people.
    */
-  async done(f) {
-    const id = f._[0] || die("usage: passalong done <id>");
+  async archive(f) {
+    const id = f._[0] || die("usage: passalong archive <id>");
     const g = await passalong.setStatus(id, "consumed").catch((e) => die(e.message));
     console.error(`${g.meta.id} archived — off your board, and it no longer counts against sync`);
   },
 
+  /** What `archive` was called. Kept so a script written against it still runs, and says so. */
+  async done(f) {
+    console.error("`passalong done` is now `passalong archive` — it archives, it does not mark work done.");
+    return commands.archive(f);
+  },
+
   async rm(f) {
     const id = f._[0] || die("usage: passalong rm <id>");
     await passalong.remove(id).catch((e) => die(e.message));
@@ -485,14 +666,40 @@ const commands = {
         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.`);
+    // An account you cannot sign in to is one that dies with this file. This used to mint one
+    // silently and then suggest adding a password afterwards; it asks up front instead.
+    if (!tty)
+      die(
+        "no terminal to ask on. Sign in at " +
+          `${api.baseUrl()}/hub, then attach this machine with \`passalong login <token>\``,
+      );
+
+    const email = f.email || (await ask("Email: "));
+    if (!email) die("an email is needed to sign in");
+    const password = await ask("Password: ", { hidden: true });
+    if (!password) die("a password is needed to sign in");
+
+    const label = `${hostname()} cli`;
+    let who = await api.signIn(email, password, { label }).catch((e) => e);
+    if (who instanceof Error) {
+      // 401 is "no such account, or the wrong password", said the same way on purpose so the API
+      // does not confirm which addresses exist. The CLI has to ask rather than guess, because
+      // creating an account for a mistyped address is worse than being told to try again.
+      if (who.status !== 401) die(who.message);
+      const yes = (await ask(`No account signed in as ${email}. Create one? [y/N] `)).toLowerCase();
+      if (yes !== "y" && yes !== "yes")
+        die("not signed in. If the password was wrong, try again, or reset it at " + `${api.baseUrl()}/hub`);
+      const again = await ask("Choose a password: ", { hidden: true });
+      if (again !== password) die("those did not match");
+      who = await api.signIn(email, password, { make: true, label }).catch((e) => die(e.message));
+    }
+
+    store.writeConfig({ token: who.token, api: api.baseUrl() });
+    console.error(`signed in as ${email} (account ${who.account}) on ${api.baseUrl()}. Sync is on.`);
     console.error("Attach other machines with:");
-    console.error(`  passalong login ${token}`);
+    console.error(`  passalong login ${who.token}`);
     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) {
@@ -598,14 +805,18 @@ const commands = {
     // over them, and a no-op when they are already there.
     const settingsPath = join(homedir(), ".claude", "settings.json");
     try {
-      const { withHooks } = await import("../src/hooks.js");
+      const { withHooks, withStatusLine } = await import("../src/hooks.js");
       const before = existsSync(settingsPath) ? JSON.parse(readFileSync(settingsPath, "utf8")) : {};
-      const after = withHooks(before);
+      const after = withStatusLine(withHooks(before));
+      if (before.statusLine && before.statusLine.command !== "passalong now --statusline")
+        console.error(
+          "you already have a status line, so it was left alone. To show Passalong in it, call `passalong now --statusline` from your script",
+        );
       if (JSON.stringify(after) === JSON.stringify(before)) console.error("Claude Code hooks already installed");
       else {
         mkdirSync(dirname(settingsPath), { recursive: true });
         writeFileSync(settingsPath, `${JSON.stringify(after, null, 2)}\n`);
-        console.error(`installed Claude Code hooks (session start, stop) → ${settingsPath}`);
+        console.error(`installed Claude Code hooks (session start, stop) and status line → ${settingsPath}`);
       }
     } catch (err) {
       console.error(`could not install Claude Code hooks (${err.message}); ${settingsPath} left as it was`);
@@ -621,7 +832,18 @@ const commands = {
    * nothing at all when anything goes wrong — a hook must never get in the way of a session.
    */
   async now(f) {
-    const { nowText, stopVerdict } = await import("../src/hooks.js");
+    const { nowText, statusText, stopVerdict } = await import("../src/hooks.js");
+    // The status line: printed from a cache, refreshed behind it. Claude Code cancels a status
+    // line still running when the next update comes, so this never waits on the network.
+    if (f.statusline) return statusLine(f);
+    if (f["statusline-refresh"]) {
+      const cwd = typeof f["statusline-refresh"] === "string" ? f["statusline-refresh"] : process.cwd();
+      try {
+        const r = await passalong.now({ cwd });
+        writeStatus(cwd, statusText({ held: r.held, needs: r.needs, ready: r.waiting.ready }));
+      } catch {}
+      return;
+    }
     if (!f.hook) {
       const r = await passalong.now();
       console.log(nowText(r) || "Nothing held here, and nothing waiting.");
@@ -659,6 +881,15 @@ const commands = {
     await serve();
   },
 
+  /**
+   * Ask the registry what the latest version is and write it down. Not in the help, because it is
+   * not for a person: `passalong` spawns it, detached, when the answer on file is a day old.
+   */
+  async ["refresh-update"]() {
+    const { refresh } = await import("../src/update.js");
+    await refresh();
+  },
+
   async help() {
     const src = readFileSync(fileURLToPath(import.meta.url), "utf8");
     const lines = src.split("\n").filter((l) => l.startsWith("//   passalong "));
@@ -675,5 +906,42 @@ const cmd = argv._.shift() || "help";
 // `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));
+} else if (cmd === "--help" || cmd === "-h" || cmd === "help") commands.help();
+// A command this build does not have used to print the help page and exit 0, which reads as "that
+// command exists and did nothing" — and the usual cause is an older passalong, where the command is
+// in the docs and not in the binary. So it fails, names what it does not know, and says the version
+// it is, which is the fact that explains it.
+else if (!commands[cmd])
+  die(
+    `unknown command "${cmd}" — run \`passalong help\` for the list. ` +
+      `This is passalong ${JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version}; ` +
+      "if you expected this command, `npm i -g passalong` for the newest one.",
+  );
+else {
+  await commands[cmd](argv).catch((e) => die(e.message));
+  // After the command, never before it: a version check is not worth a millisecond of somebody's
+  // first impression, and it must never be the reason a command felt slow. `mcp` is a server that
+  // does not return, and the hooks are read by an agent rather than a person — a line neither of
+  // them asked for is noise in a transcript.
+  if (!["mcp", "now", "refresh-update"].includes(cmd)) {
+    try {
+      const { cachedNotice } = await import("../src/update.js");
+      const current = JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version;
+      const { notice, stale } = cachedNotice({ current });
+      if (notice) console.error(notice);
+      // The refresh is a process this one does not wait for: detached, output thrown away,
+      // unref'd so the exit is not held open by it. Measuring the alternative is what settled it —
+      // the registry took six to ten seconds to answer, so awaiting it meant every command paid
+      // that or the check silently never worked.
+      if (stale) {
+        const child = spawn(process.execPath, [fileURLToPath(import.meta.url), "refresh-update"], {
+          detached: true,
+          stdio: "ignore",
+        });
+        child.unref();
+      }
+    } catch {
+      // Nothing about being out of date is worth failing a command that already worked.
+    }
+  }
+}

package/package.json

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

@@ -9,6 +9,31 @@ You are turning this session into a **transfer guide**: executable context for 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.
 
+## Before you write anything
+
+**Check what is already open, and whether a guide is wanted at all.** Run `passalong now` (or
+`take` with no id over MCP) to see what this worktree holds and what was handed to you.
+
+- **The session answers something you hold** — hand it in (`passalong hand_in <id> …`) instead.
+  Publishing a second guide about it leaves two records of one piece of work. Every hand-in carries
+  what you ran and what came back — the command and the lines that decided it, a test summary, a
+  link to the change, or a screenshot url. Copy each one out of the session as you go; at the end
+  you would be writing from memory, which is what evidence exists to replace. On a **task**, send
+  it as `checks`: one entry per Acceptance line, each with that line and the evidence for it. Its
+  author reads them line against line, and evidence filed under the check it answers is worth more
+  than the same output in one block. On a handoff or a bug, which have no Acceptance lines, send
+  `evidence` as one block.
+- **The work never left this repo** — committed and pushed on a branch the team can already see,
+  with a pull request to review — then it has crossed no boundary, and a transfer guide is one more
+  thing for somebody to read. What is worth publishing from a session like that is what is *still
+  open*: file it as a bug (`kind: bug`) or a task, not as a write-up of the fix.
+- **The ask is vague** — "update the passalong", "add this to passalong", "log this" — it may mean
+  hand in what you hold, add a follow-up to a guide, or publish something new. Ask which, in one
+  line. Publishing the wrong thing costs somebody a review, and the author a guide to delete.
+
+A transfer guide earns its place when the work has to cross a boundary: another repo, another
+machine, another agent session, or a teammate without your branch.
+
 ## Procedure
 
 1. **Pick the one thing to transfer.** If the user named it (`/passalong-capture <what>` or
@@ -37,7 +62,9 @@ session's history. Write for execution, not for permanence.
    **If what you are capturing is more context for an existing guide** — a missing detail, a step
    that needed explaining, what changed since, what you found doing it — add `--follows <that id>`.
    That publishes it as a follow-up: its own guide, listed under the original, and handed to
-   whoever opens the original, person or agent. A session that started from a passalong guide
+   whoever opens the original, person or agent. It travels the other way too — whoever opens the
+   follow-up gets the guide it came out of, and where that guide has got to — so write it as a
+   note on that work rather than as a standalone brief. A session that started from a passalong guide
    (`passalong start` or `pull` on an id, or an agent opened one) usually has context worth adding
    this way. Whether the guide worked is still its own answer: `passalong works <id>` or
    `passalong broken <id> <why>`.

package/src/api.js

@@ -63,7 +63,58 @@ const q = (params) => {
   return s ? `?${s}` : "";
 };
 
-/** Mint a fresh account and return its token. No email, no password: the token is the account. */
+/**
+ * Sign in, or make the account, and come back with a token for this machine.
+ *
+ * Three calls, because the API answers a browser and this is not one: signing in sets a session
+ * cookie, and the CLI carries a bearer token instead — one that shows up in the hub's token list
+ * with a name on it, and can be revoked there without changing the password. So the cookie is used
+ * once, to mint the token, and then dropped.
+ *
+ * `make` is signup rather than sign-in. It is the caller's decision and not a fallback here: an
+ * account created because an address was mistyped is worse than being told there is no such
+ * account.
+ */
+export async function signIn(email, password, { make = false, label = "" } = {}) {
+  const res = await fetch(`${baseUrl()}${make ? "/v1/auth/signup" : "/v1/auth/login"}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ email, password }),
+  }).catch((err) => {
+    throw new ApiError(0, `could not reach ${baseUrl()} (${err.message})`);
+  });
+  if (!res.ok) {
+    const said = await res.json().catch(() => ({}));
+    throw new ApiError(res.status, said.message || res.statusText);
+  }
+  const { account } = await res.json();
+  // `getSetCookie` keeps the cookies apart; a joined `set-cookie` header cannot be split safely,
+  // because an Expires date has a comma in it.
+  const cookie = (res.headers.getSetCookie?.() ?? []).map((c) => c.split(";")[0]).join("; ");
+  if (!cookie) throw new ApiError(500, "signed in, but no session came back");
+
+  const minted = await fetch(`${baseUrl()}/v1/tokens`, {
+    method: "POST",
+    headers: { "content-type": "application/json", cookie },
+    body: JSON.stringify({ name: label || "cli" }),
+  });
+  if (!minted.ok) {
+    const said = await minted.json().catch(() => ({}));
+    throw new ApiError(minted.status, said.message || "could not make a token for this machine");
+  }
+  const { token: made } = await minted.json();
+  return { account, token: made };
+}
+
+/**
+ * Mint an account with no email and no password.
+ *
+ * Nothing in this package calls it any more — `passalong login` asks for an email and a password,
+ * because an account nobody can sign in to is one that dies with the file it is stored in, and the
+ * CLI used to make one without ever saying so. It stays exported because the route it calls is
+ * still live and still right for the invite page, which mints before it claims, and because
+ * removing a published export is a breaking change for anyone who imported it.
+ */
 export const createAccount = () => call("/v1/accounts", { method: "POST", auth: false });
 export const me = () => call("/v1/me");
 export const updateMe = (patch) => call("/v1/me", { method: "PATCH", body: patch });
@@ -101,6 +152,26 @@ export const get = (id) => call(`/v1/guides/${id}`, { raw: true });
  */
 export const children = (id, { markdown = false } = {}) =>
   call(`/v1/guides/${encodeURIComponent(id)}/children${q({ markdown: markdown ? "1" : "" })}`);
+/**
+ * The guide this one came out of, with where it has got to. `markdown` adds its content. Like the
+ * follow-ups, reading it is not opening it: no pull is recorded on the parent.
+ */
+export const parent = (id, { markdown = false } = {}) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/parent${q({ markdown: markdown ? "1" : "" })}`);
+/**
+ * Giving a plan away, for whoever the deployment names in `ADMIN_ACCOUNTS`. Every other account
+ * gets a 404 from these, so the CLI does not have to know who the operator is either.
+ */
+export const makeAdmin = (email) => call("/v1/admin/accounts", { method: "POST", body: { email } });
+export const listAdmins = () => call("/v1/admin/accounts");
+export const grantAdmin = (who) =>
+  call(`/v1/admin/accounts/${encodeURIComponent(who)}`, { method: "PUT", body: {} });
+export const revokeAdmin = (who) =>
+  call(`/v1/admin/accounts/${encodeURIComponent(who)}`, { method: "DELETE" });
+export const giveGift = (body) => call("/v1/admin/gifts", { method: "POST", body });
+export const listGifts = () => call("/v1/admin/gifts");
+export const takeGiftBack = (id) =>
+  call(`/v1/admin/gifts/${encodeURIComponent(id)}`, { method: "DELETE" });
 export const setStatus = (id, status) =>
   call(`/v1/guides/${id}/status`, { method: "PATCH", body: { status } });
 export const remove = (id) => call(`/v1/guides/${id}`, { method: "DELETE" });
@@ -122,6 +193,9 @@ export const releaseTask = (id) =>
   call(`/v1/tasks/${encodeURIComponent(id)}/release`, { method: "POST", body: {} });
 /** The four verbs every guide answers to. See docs/V2.md §11. */
 export const working = () => call("/v1/working");
+export const handedIn = () => call("/v1/handed_in");
+export const assign = (id, to) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/assign`, { method: "POST", body: { to } });
 export const take = (body) => call("/v1/take", { method: "POST", body });
 export const progress = (id, body) =>
   call(`/v1/guides/${encodeURIComponent(id)}/progress`, { method: "PUT", body });