passalong 0.17.0 → 0.18.0

package/README.md

@@ -28,25 +28,24 @@ codex mcp add passalong -- passalong mcp   # Codex: the same MCP server
 ## Commands
 
 ```
-passalong share [file] [--to team[/handle]]  publish a guide → id + link; --to hands it to a team or teammate
-passalong pull <id|link>      fetch a guide into ./.passalong/ (git-ignored) and print it
+passalong share [file] [--to team[/handle]]  publish a guide as a draft → id + link; --to addresses it
+passalong pull <id|link>      print a guide; --save also writes ./.passalong/<id>.md (git-ignored)
 passalong inbox               guides handed to you that you have not pulled yet
 passalong board               waiting on you, in flight, landed, worth keeping
 passalong activity [--all]    what happened while you were away; clears unless --all
-passalong list [query]        your guides and your teams', local and synced
+passalong list [query]        your guides and your teams'
 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> <shot>   you tried it and it holds up, with a screenshot of it working
-passalong broken <id> <why>   you tried it and it does not — the author is told, with your reason
 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]       sign in from the browser, or attach this machine with a token
+passalong login               sign in from the browser
+passalong login --with-token  read a token from stdin instead (CI, scripts)
 passalong login --new         add another account to this machine
 passalong accounts            the accounts signed in here, and which is the default
 passalong use <name>          make one of them the default
-passalong logout <name>       forget one of them
+passalong logout [name]       forget one of them (default: the current one)
 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)
@@ -74,11 +73,10 @@ passalong inbox                         # on Ada's side: what was handed to you
 passalong activity                      # back on your side: it landed, and who pulled it
 ```
 
-A receiver who tries the work reports back with `passalong works <id> <screenshot.png>` or
-`passalong broken <id> <why>`. That is separate from `done`, which means *implemented*: a verdict
-means it actually runs. A passing one has to show it — at least one screenshot of it working, kept
-until 5 days after the guide is closed — a failing one has to say why, and the author sees it on
-their board and in their inbox.
+Every guide, whatever its kind, moves the same way: it is a draft until a person marks it Ready
+(`passalong ready <id>`), then whoever takes it (`passalong take <id>`) holds it, hands it in with
+the evidence, and a person approves it or sends it back with the reason (`passalong approve` /
+`passalong reject`).
 
 Sign in at [the hub](https://passalong.dev/hub) with an email and password, and mint
 an API token there for the CLI and MCP servers — named, revocable, and shown once. Your password
@@ -102,10 +100,10 @@ promote them into the team's small set of maintained references.
 
 Tools: `search_guides`, `inbox`, `get_guide`, `publish_guide` (with `to`), `guide_template`, `set_guide_status`.
 
-## Guides are files
+## Guides are plain markdown
 
-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.
+Plain markdown with frontmatter, held on the server; nothing piles up on your machine. Ask for a
+file when you want one: `passalong pull <id> --save`, or `passalong export` for every guide.
 
 Point at a self-hosted server with `PASSALONG_API=https://your-host` before `passalong login`.
 

package/bin/passalong

@@ -7,25 +7,25 @@
 //     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 task "<what needs doing>"  write a task for an agent; it waits in Draft
-//   passalong ready <id...|--all> tasks you have read are ready — an agent may take them now
+//   passalong ready <id...|--all> guides you have read are ready — whoever they are for may take them now
 //   passalong tasks               every task and where it is: draft, ready, claimed, stalled, review
 //   passalong work [--once] [--agent CMD]  run an agent on each ready task here, one after another
-//   passalong approve <id>        the work in review is done
-//   passalong reject <id> <why>   not done: back to Ready, and the next agent reads why
+//   passalong approve <id>        the work in review is done, of any kind
+//   passalong reject <id> <why>   not done: back to Ready, and whoever takes it next reads why
 //   passalong release <id>        take work back from whoever holds it, of any kind
 //   passalong attach <file>       upload a picture or a file and print the markdown that points at it
 //   passalong reply <id> <text>   write to whoever holds it (--file PATH to attach); or leave a note
-//   passalong pull <id|link>      fetch a guide into ./.passalong/ and print it
-//   passalong start <id|link>     pull it and take it — one command for "I am doing this"
+//   passalong pull <id|link> [--save]  print a guide; --save also writes ./.passalong/<id>.md
+//   passalong start <id|link> [--save]  the same as take, by link as well as id
 //   passalong inbox               guides handed to you that you have not pulled yet
 //   passalong board               waiting on you, in flight, landed, worth keeping
 //   passalong activity [--all]    what happened while you were away; clears unless --all
 //   passalong log [repo]          what you did, newest first, by month
-//   passalong list [query]        your guides and your teams', local and synced
+//   passalong list [query]        your guides and your teams'
 //   passalong open <id> [--print] view a guide in the browser (or the terminal)
 //   passalong hub                 open your synced guides in the browser
-//   passalong take <id>           you are doing it — said before the work, so the sender stops guessing
-//   passalong pass <id> <why>     it is not yours — hands it back to its author with your reason
+//   passalong take <id> [--save]  you are doing it: nobody else can take it while you hold it
+//   passalong pass <id> <why>     it is not yours, or you are stuck — hands it back with your reason
 //   passalong assign <id> <to>    give it to @handle (or several: @ada @bola), a #group, or "team" — yours, or assigned to you
 //   passalong recall <id>         take back something you sent: private again, gone from their inboxes
 //   passalong admin create <email>   make an account that runs Passalong (owner only)
@@ -35,16 +35,15 @@
 //                                 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> <shot.png...>  you tried it and it holds up — with a screenshot of it working
-//   passalong broken <id> <why>   you tried it and it does not — the author is told, with your reason
 //   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]       sign in from the browser, or attach this machine with a token
+//   passalong login               sign in from the browser
+//   passalong login --with-token  read a token from stdin instead (CI, scripts)
 //   passalong login --new         add another account to this machine
 //   passalong accounts            the accounts signed in here, and which is the default
 //   passalong use <name>          make one of them the default
-//   passalong logout <name>       forget one of them
+//   passalong logout [name]       forget one of them (default: the current one)
 //   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)
@@ -65,7 +64,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import * as api from "../src/api.js";
 import { scaffold, taskScaffold } from "../src/capture.js";
-import { serialize } from "../src/guide.js";
+import { parse, serialize } from "../src/guide.js";
 import * as passalong from "../src/passalong.js";
 import * as store from "../src/store.js";
 
@@ -167,75 +166,20 @@ async function browserLogin() {
     const got = await api.devicePoll(start.id, verifier).catch((e) => die(e.message));
     if (!got) continue;
     await keepLogin(got.token);
-    console.error("Attach other machines with:");
-    console.error(`  passalong login ${got.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>");
     return;
   }
   die("nobody approved it in time. Run `passalong login` again.");
 }
 
-/** The old way, kept for anyone who asks for it with `--email`: an email and a password, typed here. */
-async function passwordLogin(f) {
-// 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));
-  }
-
-  await keepLogin(who.token);
-  console.error("Attach other machines with:");
-  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>");
-}
-
-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();
-  }
+/** A token piped in, for machines with no browser: `passalong login --with-token < token.txt`. */
+async function stdinLogin() {
+  if (process.stdin.isTTY) die("--with-token reads the token from stdin: passalong login --with-token < token.txt");
+  let raw = "";
+  for await (const chunk of process.stdin) raw += chunk;
+  const token = raw.trim();
+  if (!token) die("no token on stdin");
+  await keepLogin(token);
 }
 
 function edit(path) {
@@ -360,7 +304,7 @@ const commands = {
     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
+    const { guide, url, notified } = await passalong
       .share(readFileSync(path, "utf8"), { to, follows })
       .catch((e) => die(e.message));
     // Any draft that went out is spent, however it was named — a task that failed validation is
@@ -368,14 +312,13 @@ const commands = {
     // removeDraft() touches nothing outside the drafts directory.
     store.removeDraft(resolve(path));
     console.log(guide.meta.id);
-    console.error(`shared "${guide.meta.title}" → ${saved}`);
+    console.error(`shared "${guide.meta.title}"`);
     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)"}`,
       );
-    if (synced) console.error(`link: ${url}`);
-    else console.error("not synced (run `passalong login` to sync across machines)");
+    console.error(`link: ${url}`);
   },
 
   /**
@@ -387,7 +330,7 @@ const commands = {
     const path = store.draftPath(`task-${new Date().toISOString().replace(/[:.]/g, "-")}`);
     writeFileSync(path, taskScaffold(sentence));
     if (tty && !f["no-edit"]) edit(path);
-    const { guide, synced } = await passalong
+    const { guide } = await passalong
       .share(readFileSync(path, "utf8"))
       .catch((e) => die(`${e.message}\ndraft kept at ${path} — fix it and run \`passalong share ${path}\``));
     store.removeDraft(path);
@@ -397,7 +340,6 @@ const commands = {
     console.error(`task "${guide.meta.title}" is in Draft${target ? ` for ${target}` : " (no repo)"}`);
     if (guide.meta.team) console.error(`handed to ${guide.meta.team} (team inbox)`);
     console.error(`when an agent may take it: passalong ready ${id}`);
-    if (!synced) console.error("not synced (run `passalong login` — agents elsewhere cannot see it)");
   },
 
   async tasks() {
@@ -480,31 +422,30 @@ const commands = {
 
   async pull(f) {
     const ref = f._[0] || die("usage: passalong pull <id|link>");
-    const { guide, markdown, path, from } = await passalong.pull(ref).catch((e) => die(e.message));
+    const { guide, markdown, path } = await passalong
+      .pull(ref, { save: Boolean(f.save) })
+      .catch((e) => die(e.message));
     process.stdout.write(markdown);
-    console.error(`\npulled from ${from} → ${path}`);
+    if (path) console.error(`\nsaved to ${path}`);
     await listFollowUps(guide.meta);
   },
 
   /**
-   * Pull and take in one command. `pull` says it arrived, `take` says somebody is doing it, and
-   * they stay separate because reading a guide to decide it is not yours is what `pass` is for.
-   * This is the pair for the case where you already know: you are picking this up.
+   * Take it: you are doing it, and nobody else can take it while you hold it. The guide is printed,
+   * and `--save` also writes it to ./.passalong/. Every kind is taken the same way, and `start` is
+   * the same command by its older name, which also takes a share link.
    */
   async start(f) {
-    const ref = f._[0] || die("usage: passalong start <id|link>");
-    const r = await passalong.start(ref).catch((e) => die(e.message));
+    const ref = f._[0] || die("usage: passalong take <id|link>");
+    const r = await passalong.start(ref, { save: Boolean(f.save) }).catch((e) => die(e.message));
+    if (!r.guide?.markdown) return console.error(r.say || "nothing to take");
     process.stdout.write(r.markdown);
-    console.error(`\npulled from ${r.from} → ${r.path}`);
-    if (r.took) console.error("you are on it, and the author has been told");
-    else if (r.own) console.error("your own guide — nothing to take");
-    else if (r.ack_error) console.error(`not taken (${r.ack_error}) — run \`passalong take ${r.guide.meta.id}\``);
-    // Saying nothing here would be the silence the whole hop exists to end: you would have the
-    // guide, believe you had answered for it, and the sender would still be waiting.
-    else console.error("not taken — sync is off, so nobody was told (run `passalong login`)");
-    await listFollowUps(r.guide.meta);
+    if (r.path) console.error(`\nsaved to ${r.path}`);
+    console.error(`\nyou hold ${r.guide.id} — hand it in when it is done, or pass it with the reason`);
+    await listFollowUps(parse(r.markdown).meta);
   },
 
+
   /**
    * Upload an image and print the markdown that points at it. Evidence goes *in* the document:
    * a guide travels as markdown to whoever holds its link, so a file beside it does not travel.
@@ -612,7 +553,6 @@ const commands = {
   async list(f) {
     const scope = typeof f.team === "string" ? f.team : f.mine ? "mine" : "";
     const rows = await passalong.list(f._.join(" "), { scope });
-    if (rows.warning) console.error(`warning: ${rows.warning}`);
     if (!rows.length)
       return console.error(
         "no guides yet — run `passalong share` after your next finished piece of work",
@@ -644,17 +584,8 @@ const commands = {
     } else console.log(url);
   },
 
-  /**
-   * The first word back, before any of the work.
-   *
-   * Between a handoff and a pull the sender had no signal at all: an unanswered guide looks
-   * exactly like one nobody has noticed. These two are the hop the MCP tool and the hub already
-   * had and a terminal did not.
-   */
   async take(f) {
-    const id = f._[0] || die("usage: passalong take <id>");
-    const r = await passalong.ack(id, true).catch((e) => die(e.message));
-    console.error(`${r.id} — you are on it, and the author has been told`);
+    return commands.start(f);
   },
 
   async pass(f) {
@@ -663,10 +594,11 @@ const commands = {
     // Required, and the reason is the whole point: "not me" without "why" leaves the sender where
     // the silence did, still guessing whether to re-address it, wait, or go and ask.
     if (!why) die("say why you are passing: passalong pass <id> <why it is not yours>");
-    const r = await passalong.ack(id, false, why).catch((e) => die(e.message));
-    console.error(`${r.id} handed back — the author has been told: "${r.note}"`);
+    await passalong.pass(id, why).catch((e) => die(e.message));
+    console.error(`${id} handed back with your reason: "${why}"`);
   },
 
+
   async assign(f) {
     const id = f._[0] || die('usage: passalong assign <id> <@handle | #group | team>');
     const to = f._.slice(1).join(",") || die('say who: @handle (or several), #group, or "team" for everyone');
@@ -701,7 +633,7 @@ const commands = {
       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 ` +
+        `\n${r.email} is an admin. The token is for \`passalong login --with-token\`, the link sets their ` +
           `password for the hub, and it expires ${r.expires.slice(0, 10)}. Neither is shown again.`,
       );
       return;
@@ -755,23 +687,6 @@ const commands = {
     console.error(`${id} taken back — that plan is lapsed as of now`);
   },
 
-  async works(f) {
-    const id = f._[0] || die("usage: passalong works <id> <screenshot.png...> [what you checked]");
-    const { images, note } = passalong.proofArgs(f._.slice(1));
-    const r = await passalong.verdict(id, true, note, { images }).catch((e) => die(e.message));
-    console.error(
-      `${r.id} verified with ${images.length || "your"} screenshot${images.length === 1 ? "" : "s"} — the author has been told`,
-    );
-  },
-
-  async broken(f) {
-    const id = f._[0] || die("usage: passalong broken <id> <what happened>");
-    const why = f._.slice(1).join(" ");
-    if (!why) die("say what went wrong: passalong broken <id> <what happened>");
-    const r = await passalong.verdict(id, false, why).catch((e) => die(e.message));
-    console.error(`${r.id} reported as not working — the author has been told: "${r.note}"`);
-  },
-
   /**
    * Archive a guide: off your board, and out of what the free tier counts.
    *
@@ -806,29 +721,26 @@ const commands = {
 
   async export(f) {
     const dir = resolve(f._[0] || "passalong-export");
-    const paths = passalong.exportAll(dir);
+    const paths = await passalong.exportAll(dir).catch((e) => die(e.message));
     console.error(`exported ${paths.length} guide${paths.length === 1 ? "" : "s"} → ${dir}`);
   },
 
   async login(f) {
-    const given = f._[0];
-    if (given) {
-      await keepLogin(given);
-      return;
-    }
+    // A token on the command line lands in shell history, so it is only read from stdin.
+    if (f._[0]) die("pass a token on stdin instead: passalong login --with-token < token.txt");
+    if (f.email || f.password)
+      die("password sign-in is gone: run `passalong login` and approve it in the browser");
+    if (f["with-token"]) return stdinLogin();
     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()}`);
+        console.error(`already logged in as ${who.handle ? `@${who.handle}` : who.email || who.account}.`);
         console.error("Add another account to this machine with `passalong login --new`.");
         return;
       }
     }
-    // Passwords are for someone who asks: `--email` keeps the prompts. Everyone else is sent to the
-    // browser, which works with no terminal at all — an agent can start it, and the person it is
+    // The browser works with no terminal at all — an agent can start it, and the person it is
     // working for clicks once.
-    if (f.email || f.password) return passwordLogin(f);
     return browserLogin();
   },
 
@@ -865,7 +777,7 @@ const commands = {
 
   /** Forget one of them on this machine. The account itself is untouched: only its token here goes. */
   async logout(f) {
-    const name = f._[0] || die("usage: passalong logout <name> (see `passalong accounts`)");
+    const name = f._[0] || store.readConfig().active || die("not logged in (see `passalong accounts`)");
     const r = store.removeAccount(name);
     if (!r.removed) die(`no account called "${name}" here`);
     console.error(
@@ -1135,6 +1047,8 @@ else if (!commands[cmd])
       "if you expected this command, `npm i -g passalong` for the newest one.",
   );
 else {
+  // Once per machine; a failure leaves it for the next command rather than failing this one.
+  await passalong.tidy().catch(() => {});
   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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Hand tasks, bugs and finished work to AI coding agents, and get back a write-up with evidence.",
   "mcpName": "io.github.codellyson/passalong",
   "keywords": [

package/skill/SKILL.md

@@ -66,13 +66,13 @@ machine, another agent session, or a teammate without your branch.
    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. What you did or found while working on a
-   guide belongs in its `hand_in`, not a follow-up. Whether a guide worked is its own answer:
-   `passalong works <id> <screenshot>` or `passalong broken <id> <why>`.
-6. **Report** the id (and link if synced) and one line on how to use it on the other side:
-   `passalong start <id>` in the target repo, or "start passalong <id>" to an agent with the
-   Passalong MCP server. `start` rather than `pull` on purpose: it takes the handoff as well as
-   fetching it, and until somebody says they are on it the sender cannot tell a guide nobody
-   noticed from one somebody is deep in.
+   guide belongs in its `hand_in`, not a follow-up.
+6. **Report** the id (and link) and say it is a **draft**: it reaches nobody until the person reads
+   it and marks it Ready (`passalong ready <id>`, or Ready in the hub). Then one line on how to use
+   it on the other side: `passalong take <id>` in the target repo, or "take passalong <id>" to an
+   agent with the Passalong MCP server. `take` rather than `pull` on purpose: it holds the work as
+   well as fetching it, and until somebody takes it the sender cannot tell a guide nobody noticed
+   from one somebody is deep in.
 
 If the `passalong` command is missing, tell the user to run `npm i -g passalong && passalong setup` and
 still write the draft file so nothing is lost.

package/src/api.js

@@ -337,10 +337,17 @@ export const renameFolderDocument = (folderId, documentId, name) =>
     method: "PATCH",
     body: { name },
   });
+export const moveFolderDocument = (folderId, documentId, to, name = "") =>
+  call(`/v1/folders/${encodeURIComponent(folderId)}/documents/${encodeURIComponent(documentId)}`, {
+    method: "PATCH",
+    body: name ? { folder: to, name } : { folder: to },
+  });
 export const folderDocumentHistory = (folderId, documentId, version = 0) =>
   call(
     `/v1/folders/${encodeURIComponent(folderId)}/documents/${encodeURIComponent(documentId)}/revisions${version ? `/${version}` : ""}`,
   );
+export const shareFolder = (folderId) =>
+  call(`/v1/folders/${encodeURIComponent(folderId)}/share`, { method: "POST" });
 export const linkFolderGuide = (folderId, guide) =>
   call(`/v1/folders/${encodeURIComponent(folderId)}/guides`, { method: "POST", body: { guide } });
 export const unlinkFolderGuide = (folderId, guide) =>
@@ -372,7 +379,10 @@ export const inbox = () => call("/v1/inbox");
 export const createReport = (body) => call("/v1/reports", { method: "POST", body });
 /** One report and the issues filed under it, grouped by product area. */
 export const report = (id) => call(`/v1/reports/${encodeURIComponent(id)}`);
-export const get = (id) => call(`/v1/guides/${id}`, { raw: true });
+export const get = (id, { peek = false } = {}) =>
+  call(`/v1/guides/${id}${q({ peek: peek ? "1" : "" })}`, { raw: true });
+/** One page of every guide this account can read, for `export`. Records no pull. */
+export const exportPage = (after = "") => call(`/v1/export${q({ after })}`);
 /**
  * A guide's follow-ups, one level down. `markdown` adds each one's content, oldest first and
  * capped server-side; neither form counts as opening them.
@@ -419,6 +429,11 @@ export const approveTask = (id) =>
   call(`/v1/tasks/${encodeURIComponent(id)}/approve`, { method: "POST", body: {} });
 export const rejectTask = (id, why) =>
   call(`/v1/tasks/${encodeURIComponent(id)}/reject`, { method: "POST", body: { why } });
+/** A handoff's or bug's approve and send-back. No `place` names the only hand-in there is. */
+export const closeGuide = (id) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/close`, { method: "POST", body: {} });
+export const sendBack = (id, why) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/send_back`, { method: "POST", body: { why } });
 /** Take work back from whoever holds it, of any kind. `/v1/tasks/…/release` is the old path. */
 export const release = (id) =>
   call(`/v1/guides/${encodeURIComponent(id)}/release`, { method: "POST", body: {} });

package/src/guide.js

@@ -525,7 +525,8 @@ export function bugGuide({
   area = "",
   report = "",
   environment = "",
-  status = "published",
+  // A draft like every new guide: it reaches people when a person marks it Ready.
+  status = "draft",
   evidence = [],
 } = {}) {
   /**

package/src/mcp.js

@@ -297,11 +297,13 @@ export function buildServer() {
         "to act. It is what the person sees first in their hub; the document is behind it. A guide " +
         "with no summary is refused.\n" +
         "SAY WHICH KIND IT IS. There is no default: a guide with no `kind:` line is refused, and so " +
-        "is a spelling that is not one of the three. " +
+        "is a spelling that is not one of the three. EVERY NEW GUIDE IS A DRAFT, whatever its kind: " +
+        "it reaches nobody until a person reads it and marks it Ready, and every kind then moves the " +
+        "same way — Ready, taken, handed in, approved. " +
         `kind: task is work nobody has done yet. Sections: ${TASK_SECTIONS.join(", ")}. ` +
         "It has no Steps: work out how to reach Goal within Constraints, leave Out of scope " +
-        "alone, and treat Acceptance as the definition of done. New tasks say `status: draft`; " +
-        "a proposal awaiting a team decision stays Draft until a person makes it Ready. hand_in with `markdown`: a " +
+        "alone, and treat Acceptance as the definition of done. A proposal awaiting a team decision " +
+        "stays Draft until a person makes it Ready. hand_in with `markdown`: a " +
         "transfer guide about what you did (guide_template kind transfer shows the shape) — its " +
         "author reviews it against Acceptance.\n" +
         `kind: transfer (or no kind: line) is a finished implementation to repeat here. Sections: ${SECTIONS.join(", ")}. ` +
@@ -346,6 +348,18 @@ export function buildServer() {
         "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.\n" +
+        "A FOLDER IS A PLACE; ITS DOCUMENTS ARE WHAT TO KNOW; GUIDES ARE WHAT TO DO. Sort every " +
+        "item before writing it into a folder. If someone still has to act on it — a defect that " +
+        "is still open, work not yet done, a check nobody has run — it is a guide: kind bug for " +
+        "something broken, kind task for work to do. Publish it and link_folder_guide it into the " +
+        "folder; a guide has an owner, a state and an answer. A document has none of those and " +
+        "tells nobody, so open work recorded only as a document is lost. If it is what someone " +
+        "needs to know — an overview, a decision, a finding, something already fixed with its " +
+        "commit — it is a document. An incident is both: one overview document, a document per " +
+        "resolved finding, and a bug or task guide per open item, all in the incident's folder. " +
+        "WHERE A FOLDER LIVES is in the `space` field of create_folder and get_folder: private, " +
+        "or a named team. Tell the person that, never what you meant to do; a folder made without " +
+        "`team` is private, and a subfolder takes its parent's space.\n" +
         "FOLDERS ARE REUSABLE PROJECT CONTEXT, NOT GUIDES. When the user asks for a folder for a " +
         "script, brief, assets or work spanning several guides, call list_folders first to avoid " +
         "making a duplicate. If none fits, call create_folder with a title and short description. " +
@@ -366,8 +380,11 @@ export function buildServer() {
         "unlink_folder_guide takes it out again. Delete a document or file with " +
         "delete_folder_document or delete_folder_asset only when the person asked for it to go: " +
         "neither can be undone. No tool deletes a whole folder; a person does that in the hub. " +
+        "share_folder returns a link anyone can read the folder by, like a guide's; use it only " +
+        "when the person asked to share the folder. " +
         "list_folders with query finds folders and documents by their words, and with guide the " +
-        "folders a guide is in. rename_folder_document renames a document; " +
+        "folders a guide is in. rename_folder_document renames a document and move_folder_document " +
+        "moves it to another folder in the same space, keeping its history; " +
         "get_folder_document_history reads earlier versions, so a bad edit can be put back.\n" +
         "A FOLLOW-UP IS MORE CONTEXT FOR A GUIDE, WRITTEN AS ITS OWN GUIDE. When a guide needs " +
         "more context — a missing detail, a step that needed explaining, what changed since, what " +
@@ -404,15 +421,6 @@ export function buildServer() {
   async function doTake({ id, cwd, any }) {
     const dir = cwd || process.cwd();
     try {
-      // Without sync there is no claim to make; a guide by id can still be read and worked from.
-      if (!api.loggedIn() && id) {
-        const r = await passalong.pull(id, { cwd: dir });
-        return text(
-          `${leadFor(parse(r.markdown).meta)}${r.markdown}\n\n<!-- passalong: not logged in, so ` +
-            "nobody was told you took it; written to " +
-            `${r.path} -->`,
-        );
-      }
       const r = await passalong.take(id, { cwd: dir, any: Boolean(any) });
       if (!r.guide) return text(nextNote(r) || "Nothing is waiting for this agent here.");
       const meta = parse(r.guide.markdown).meta;
@@ -421,8 +429,7 @@ export function buildServer() {
       const from = await passalong.parentGuide(meta);
       const held =
         `<!-- passalong: ${r.guide.id} is yours` +
-        `${r.guide.resumed ? " (you already held it — carry on from where it was left)" : ""}; ` +
-        `written to ${r.path}. -->`;
+        `${r.guide.resumed ? " (you already held it — carry on from where it was left)" : ""}. -->`;
       const said = repliesNote(r.replies);
       return text(
         `${said ? `${said}\n\n` : ""}${from}${leadFor(meta)}${r.guide.markdown}${siblings}${context ? `\n\n${context}` : ""}` +
@@ -559,7 +566,7 @@ export function buildServer() {
       title: "Create project folder",
       annotations: ADDS,
       description:
-        "Create a folder or nested subfolder after checking list_folders. Pass parent to nest it; omit team for a private root, and pass a team slug only when sharing was requested. A subfolder inherits its parent's space.",
+        "Create a folder or nested subfolder after checking list_folders. Pass parent to nest it; omit team for a private root, and pass a team slug only when sharing was requested. A subfolder inherits its parent's space. The answer's `space` says where it landed: report that to the person.",
       inputSchema: {
         title: z.string().describe("Name of the project or body of work"),
         description: z.string().optional().describe("Short purpose of the folder"),
@@ -702,7 +709,8 @@ export function buildServer() {
     {
       title: "Write new folder document",
       annotations: ADDS,
-      description: "Add Markdown such as a brief or script to a folder.",
+      description:
+        "Add a Markdown document to a folder: reference to read, such as a brief, script, overview or a finding already resolved. It has no owner and no state and notifies nobody, so anything someone must still act on (an open bug, work to do) belongs in a bug or task guide linked to the folder instead.",
       inputSchema: { folder: z.string(), name: z.string(), body: z.string() },
     },
     async ({ folder, name, body }) => {
@@ -752,6 +760,45 @@ export function buildServer() {
       }
     },
   );
+  server.registerTool(
+    "share_folder",
+    {
+      title: "Share folder link",
+      annotations: ADDS,
+      description:
+        "Get the folder's share link, making one if it has none: like a guide's link, anyone holding it can read the folder and the folders inside it and download its files, with no account. Linked guides are not included. Call it only when the person asked to share the folder or for its link; stopping sharing is done in the hub.",
+      inputSchema: { folder: z.string() },
+    },
+    async ({ folder }) => {
+      try {
+        return json(await api.shareFolder(folder));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+  server.registerTool(
+    "move_folder_document",
+    {
+      title: "Move folder document",
+      annotations: ADDS,
+      description:
+        "Move a folder document into another folder in the same space, private or the same team. It keeps its id, text and history; pass name too to rename it on the way. Refused if the other folder already has a document by that name.",
+      inputSchema: {
+        folder: z.string().describe("The folder the document is in now"),
+        document: z.string(),
+        to: z.string().describe("The folder to move it into"),
+        name: z.string().optional().describe("A new name, if it should change too"),
+      },
+    },
+    async ({ folder, document, to, name }) => {
+      try {
+        return json(await api.moveFolderDocument(folder, document, to, name || ""));
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
   server.registerTool(
     "get_folder_document_history",
     {
@@ -852,7 +899,7 @@ export function buildServer() {
       annotations: READS,
       description:
         "Search transfer guides by words in the title, tags, stack, or body: the user's own " +
-        "(local and synced) plus every team they belong to. Empty query lists everything, newest first.",
+        "plus every team they belong to. Empty query lists everything, newest first.",
       inputSchema: {
         query: z.string().default(""),
         scope: z.string().optional().describe('"mine", "all" (default), or a team slug'),
@@ -861,7 +908,7 @@ export function buildServer() {
     async ({ query, scope }) => {
       try {
         const rows = await passalong.list(query, { scope: scope || "" });
-        return json({ guides: rows, warning: rows.warning });
+        return json({ guides: rows });
       } catch (err) {
         return fail(err);
       }
@@ -1288,18 +1335,13 @@ export function buildServer() {
       description:
         "READ a transfer guide by passalong id or share link and return its markdown. A guide over " +
         "20,000 characters comes back as an outline (its headings and their sizes) unless you ask " +
-        "for `section`, for one part, or `full`, for all of it. Also " +
-        "writes it to .passalong/<id>.md in the working directory so it survives the session. " +
+        "for `section`, for one part, or `full`, for all of it. Nothing is written to disk. " +
         "Pulling a teammate's guide tells them the transfer landed. Use this to look at a guide " +
         "you have not committed to. If you are about to DO the work, call take instead: " +
         "it does this and takes it in one call, which is the only way the sender learns " +
         "somebody picked it up.",
       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"),
         section: z
           .string()
           .optional()
@@ -1314,23 +1356,23 @@ export function buildServer() {
           .describe("the whole document, even one over 20,000 characters"),
       },
     },
-    async ({ ref, cwd, section, outline, full }) => {
+    async ({ ref, section, outline, full }) => {
       try {
-        const { markdown, path, from } = await passalong.pull(ref, { cwd: cwd || process.cwd() });
+        const { markdown, from } = await passalong.pull(ref);
         const meta = parse(markdown).meta;
         if (section) {
           const part = sectionOf(markdown, section);
           if (!part)
             return text(
-              `No heading matching "${section}".\n\n${outlineText(markdown, { id: meta.id || ref, path })}`,
+              `No heading matching "${section}".\n\n${outlineText(markdown, { id: meta.id || ref })}`,
             );
           return text(
-            `${part.text}\n\n<!-- passalong: ${meta.id || ref}, "${part.heading}" only; the whole guide is at ${path} -->`,
+            `${part.text}\n\n<!-- passalong: ${meta.id || ref}, "${part.heading}" only; ask with full: true for the whole guide -->`,
           );
         }
         if (outline || (!full && markdown.length > GUIDE_WARN))
           return text(
-            `${outlineText(markdown, { id: meta.id || ref, path })}\n\n<!-- passalong: ${from}; written to ${path} -->`,
+            `${outlineText(markdown, { id: meta.id || ref })}\n\n<!-- passalong: ${from} -->`,
           );
         const lead = leadFor(meta);
         const siblings = await related(meta);
@@ -1347,7 +1389,7 @@ export function buildServer() {
         // warning against executing the document, so being read first is its whole job.
         return text(
           `${follows}${lead}${markdown}${siblings}${context ? `\n\n${context}` : ""}` +
-            `\n\n<!-- passalong: ${from}; written to ${path} -->` +
+            `\n\n<!-- passalong: ${from} -->` +
             `\n${passalong.handoffNudge(meta)}` +
             `\n${passalong.followUpNote(meta)}`,
         );
@@ -1517,7 +1559,7 @@ export function buildServer() {
     },
     async ({ markdown, to, cwd, parent }) => {
       try {
-        const { guide, url, synced, notified, path } = await passalong.share(markdown, {
+        const { guide, url, synced, notified } = await passalong.share(markdown, {
           cwd: cwd || process.cwd(),
           to,
           follows: parent,
@@ -1531,11 +1573,10 @@ export function buildServer() {
           to: guide.meta.to || "",
           parent: guide.meta.parent || "",
           notified,
-          path,
           ...(sizeWarning(markdown.length) ? { warning: sizeWarning(markdown.length) } : {}),
-          // A task does not go live on publish, and an agent that reports "queued it" has told
-          // the user something untrue. Said in the result so it is said to them.
-          ...(guide.meta.kind === "task" && guide.meta.status === "draft"
+          // Nothing goes live on publish, and an agent that reports "sent it" or "queued it" has
+          // told the user something untrue. Said in the result so it is said to them.
+          ...(guide.meta.status === "draft"
             ? {
                 status: "draft",
                 next: `in Draft: ask the user to read it, then run \`passalong ready ${guide.meta.id}\``,
@@ -1636,7 +1677,11 @@ export function buildServer() {
           { title: title || "", environment: environment || "", issues },
           { cwd: cwd || process.cwd(), to },
         );
-        return json(filed);
+        return json({
+          ...filed,
+          // Filed is not sent: every bug is a draft until a person reads it.
+          next: "all in Draft: ask the user to read them, then run `passalong ready --all`",
+        });
       } catch (err) {
         return fail(err);
       }
@@ -1745,5 +1790,6 @@ export function buildServer() {
 
 /** The stdio server: `passalong mcp`, and what `passalong setup` registers with a client. */
 export async function serve() {
+  passalong.tidy().catch(() => {});
   await buildServer().connect(new StdioServerTransport());
 }

package/src/passalong.js

@@ -78,26 +78,19 @@ export async function share(markdown, { cwd = process.cwd(), to, follows } = {})
   ];
   if (errors.length)
     throw new PassalongError(`guide is not ready to share:\n  - ${errors.join("\n  - ")}`);
-  // A task stays a draft when it is shared. Draft is the column a task waits in until a person
-  // says it is ready for an agent — `ready()` — and an agent that drafts one over MCP comes
-  // through here too, so publishing on share would let a task queue itself with nobody reading it.
-  if (guide.meta.status === "draft" && guide.meta.kind !== "task")
-    guide = { ...guide, meta: { ...guide.meta, status: "published" } };
-
-  let url = guide.meta.url || null;
-  let synced = false;
-  let notified = false;
-  if (api.loggedIn()) {
-    const res = await api.publish(guide.meta.id, serialize(guide));
-    url = res.url;
-    synced = true;
-    notified = Boolean(res.notified);
-    guide = { ...guide, meta: { ...guide.meta, url } };
-  } else if (guide.meta.team) {
-    throw new PassalongError("sharing to a team needs sync — run `passalong login` first");
-  }
-  const path = store.save(guide);
-  return { guide, path, url, synced, notified };
+  // Every guide is a draft when it is first shared, whatever its kind: Draft is where it waits
+  // until a person says it is ready — `ready()` — and an agent that writes one over MCP comes
+  // through here too, so publishing on share would let it reach people with nobody reading it.
+  // Sharing *is* putting it in Draft, so a new guide that names no status says so here; one already
+  // published keeps what its document says.
+  if (!guide.meta.status) guide = { ...guide, meta: { ...guide.meta, status: "draft" } };
+
+  // The server is where a guide lives; nothing is kept on this machine.
+  needsSync("sharing a guide");
+  const res = await api.publish(guide.meta.id, serialize(guide));
+  const url = res.url;
+  guide = { ...guide, meta: { ...guide.meta, url } };
+  return { guide, url, synced: true, notified: Boolean(res.notified) };
 }
 
 /**
@@ -151,8 +144,11 @@ export async function fileBugs(
   return { report: { id: report.id, title, environment, team }, issues: filed };
 }
 
-/** Resolve a reference (id, share URL, or local file path) to a guide. */
-export async function resolve(ref) {
+/**
+ * Resolve a reference (id, share URL, or local file path) to a guide. An id is the server's to
+ * answer: nothing keeps a copy on this machine. `peek` reads without recording a pull.
+ */
+export async function resolve(ref, { peek = false } = {}) {
   if (/^https?:\/\//.test(ref)) {
     const md = await api.fetchShared(ref);
     return { guide: parse(md), from: "link" };
@@ -162,21 +158,13 @@ export async function resolve(ref) {
   }
   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;
-    }
+  needsSync("reading a guide by id");
+  try {
+    return { guide: parse(await api.get(ref, { peek })), from: "sync" };
+  } catch (err) {
+    if (err.status === 404) throw new PassalongError(`no guide "${ref}"`);
+    throw err;
   }
-  throw new PassalongError(
-    `no guide "${ref}" (not local${api.loggedIn() ? " or synced" : "; not logged in, so sync was not checked"})`,
-  );
 }
 
 /**
@@ -201,22 +189,21 @@ export async function resolveId(ref) {
 }
 
 /**
- * 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. A pull of someone else's
- * guide is also recorded server-side, which is how the sender sees the transfer landed.
+ * Pull a guide and return it, so the caller can put the text straight into an agent's context. A
+ * pull of someone else's guide is recorded server-side, which is how the sender sees the transfer
+ * landed. Nothing is written unless `save` asks: then it lands in `.passalong/<id>.md` here.
  */
-export async function pull(ref, { cwd = process.cwd(), write = true } = {}) {
+export async function pull(ref, { cwd = process.cwd(), save = false } = {}) {
   const { guide, from } = await resolve(ref);
-  // A locally cached copy of a teammate's guide still counts as a pull for them.
-  if (from === "local" && api.loggedIn() && guide.meta.team) {
-    api.get(guide.meta.id).catch(() => {});
-  }
-  let path = null;
-  if (write) {
-    path = join(localDir(cwd), `${guide.meta.id}.md`);
-    writeFileSync(path, serialize(guide));
-  }
-  return { guide, from, path, markdown: serialize(guide) };
+  const markdown = serialize(guide);
+  return { guide, from, path: save ? saveTo(cwd, guide.meta.id, markdown) : null, markdown };
+}
+
+/** Write a guide into `.passalong/<id>.md` under `cwd`, when somebody asked for a file. */
+function saveTo(cwd, id, markdown) {
+  const path = join(localDir(cwd), `${id}.md`);
+  writeFileSync(path, markdown);
+  return path;
 }
 
 /**
@@ -284,17 +271,13 @@ export async function tasks() {
 
 /**
  * Take the next task for this worktree's repo, or get back the one this worktree already holds.
- * `null` when there is nothing to do. The guide is written to `.passalong/<id>.md` like a pull.
+ * `null` when there is nothing to do. Written to `.passalong/<id>.md` only when `save` asks.
  */
-export async function nextTask({ cwd = process.cwd(), any = false } = {}) {
+export async function nextTask({ cwd = process.cwd(), any = false, save = false } = {}) {
   needsSync("taking a task");
   const { task } = await api.nextTask({ ...agent(cwd), any });
   if (!task) return null;
-  const guide = parse(task.markdown);
-  const path = join(localDir(agent(cwd).worktree), `${task.id}.md`);
-  writeFileSync(path, task.markdown);
-  store.save(guide);
-  return { ...task, path };
+  return { ...task, path: save ? saveTo(agent(cwd).worktree, task.id, task.markdown) : null };
 }
 
 /** Word from the agent holding a task: renews its lease, and `note` becomes the board's line. */
@@ -397,18 +380,15 @@ export async function finishTask(
  * `next`, the calls that make sense from here, and `say` when the move is to stop.
  *
  * take: this worktree's agent takes guide `id`, or with no id the next one waiting for it. The
- * document is written to `.passalong/<id>.md`, like a pull, so the agent works from a file.
+ * document comes back in the answer, and is written to `.passalong/<id>.md` only when `save` asks.
  */
-export async function take(id, { cwd = process.cwd(), any = false } = {}) {
+export async function take(id, { cwd = process.cwd(), any = false, save = false } = {}) {
   needsSync("taking work");
   const who = agent(cwd);
   const r = await api.take({ ...who, ...(id ? { id: await resolveId(id) } : {}), any });
   if (!r.guide?.markdown) return r;
   rememberFence(r.guide.id, r.guide.fence, cwd);
-  const path = join(localDir(who.worktree), `${r.guide.id}.md`);
-  writeFileSync(path, r.guide.markdown);
-  store.save(parse(r.guide.markdown));
-  return { ...r, path };
+  return { ...r, path: save ? saveTo(who.worktree, r.guide.id, r.guide.markdown) : null };
 }
 
 /** Word from the agent that holds it: the lease starts again, and `note` is what the hub shows. */
@@ -613,16 +593,19 @@ export async function now({ cwd = process.cwd() } = {}) {
  * line the next reader needs.
  */
 export async function approveTask(id) {
-  needsSync("approving a task");
-  const r = await api.approveTask(id);
+  needsSync("approving work");
+  const { guide } = await resolve(id, { peek: true });
+  const r = await (guide.meta.kind === "task" ? api.approveTask(id) : api.closeGuide(id));
   store.remove(id);
   return r;
 }
 
 export async function rejectTask(id, why) {
-  needsSync("rejecting a task");
-  if (!String(why || "").trim()) throw new PassalongError("say why: the next agent reads it");
-  const r = await api.rejectTask(id, why);
+  needsSync("sending work back");
+  if (!String(why || "").trim())
+    throw new PassalongError("say why: whoever takes it next reads it");
+  const { guide } = await resolve(id, { peek: true });
+  const r = await (guide.meta.kind === "task" ? api.rejectTask(id, why) : api.sendBack(id, why));
   store.remove(id);
   return r;
 }
@@ -662,17 +645,10 @@ export async function release(id) {
  *   - anything else is reported in `ack_error` rather than swallowed, because an ack that quietly
  *     did not land leaves the sender in the silence the whole feature exists to end.
  */
-export async function start(ref, { cwd = process.cwd(), write = true } = {}) {
-  const pulled = await pull(ref, { cwd, write });
-  const id = pulled.guide.meta.id;
-  if (!api.loggedIn()) return { ...pulled, took: false, ack_error: "", own: false };
-  try {
-    await api.ack(id, true, "");
-    return { ...pulled, took: true, ack_error: "", own: false };
-  } catch (err) {
-    if (err.status === 403) return { ...pulled, took: false, ack_error: "", own: true };
-    return { ...pulled, took: false, ack_error: err.message, own: false };
-  }
+export async function start(ref, { cwd = process.cwd(), save = false } = {}) {
+  const r = await take(await resolveId(ref), { cwd, save });
+  if (!r.guide?.markdown) return r;
+  return { ...r, markdown: r.guide.markdown };
 }
 
 /**
@@ -949,24 +925,11 @@ export async function parentGuide(
   }
 }
 
-/** 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);
-  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, scope);
-      for (const r of res.guides) {
-        const row = seen.has(r.id) ? rows.find((x) => x.id === r.id) : null;
-        if (row) Object.assign(row, r, { where: "synced" });
-        else rows.push({ ...r, where: "synced" });
-      }
-    } catch (err) {
-      rows.warning = `sync unavailable: ${err.message}`;
-    }
-  }
-  return rows.sort((a, b) => (b.created || "").localeCompare(a.created || ""));
+/** Guides on the server this account can see, newest first, optionally filtered. */
+export async function list(query = "", { scope = "" } = {}) {
+  needsSync("listing guides");
+  const res = await api.list(query, scope);
+  return res.guides.map((r) => ({ ...r, where: "synced" }));
 }
 
 /** Guides handed to you (or your teams) that you have not pulled yet. Needs sync. */
@@ -1007,64 +970,6 @@ export async function activity({ all = false, limit = 50 } = {}) {
  * `done` says "I implemented it", a verdict says "I tried it and it holds up" — or does not.
  * A failing verdict needs a note; "it doesn't work" without a reason helps nobody.
  */
-/**
- * Say whether a guide held, and why at the length that takes.
- *
- * The reason used to be one field, capped at 280 characters by the row it was written for — so an
- * agent that had run the Verification and found it did not hold published a guide called
- * "Correction: …" instead, because measurements, commands and commit ids do not fit in a tweet.
- * The first line is the summary a row shows; the whole thing is what the guide shows.
- */
-export async function verdict(id, ok, note = "", { images = [] } = {}) {
-  if (!api.loggedIn()) throw new PassalongError("verdicts need sync — run `passalong login` first");
-  const said = note.trim();
-  if (!ok && !said)
-    throw new PassalongError("say what went wrong: passalong broken <id> <what happened>");
-  // "It works" is shown, not said: the server refuses one with no screenshot of it working, so
-  // the refusal is said here before anything is uploaded, in the words of the command that fixes it.
-  if (ok && !images.length && !/\/v1\/shots\/[a-z0-9]{6,16}/.test(said))
-    throw new PassalongError(
-      "show it working: passalong works <id> <screenshot.png> [what you checked]",
-    );
-  const guide = await resolveId(id);
-  const shots = [];
-  for (const file of images) shots.push((await attach(file)).markdown);
-  const line = said.split("\n")[0].slice(0, 280);
-  const detail = [said.length > line.length || shots.length ? said : "", ...shots]
-    .filter(Boolean)
-    .join("\n");
-  return api.verdict(guide, ok, line, detail);
-}
-
-/**
- * The words after `passalong works <id>`, split into the screenshots and the note: an argument is a
- * screenshot when it names an image file that exists, and everything else is what was checked.
- */
-export function proofArgs(args) {
-  const images = [];
-  const words = [];
-  for (const a of args) {
-    const ext = a.slice(a.lastIndexOf(".")).toLowerCase();
-    if (SHOT_TYPES[ext] && existsSync(a)) images.push(a);
-    else words.push(a);
-  }
-  return { images, note: words.join(" ") };
-}
-
-/**
- * Say whether you are taking a guide someone handed you — before doing any of it.
- *
- * The hop the product had no signal for: until this, a handoff nobody had answered looked exactly
- * like one nobody had noticed. Passing needs a reason for the same cause a failing verdict does —
- * "not me" without "why" leaves the sender where the silence did.
- */
-export async function ack(id, taken, note = "") {
-  if (!api.loggedIn()) throw new PassalongError("acks need sync — run `passalong login` first");
-  if (!taken && !note.trim())
-    throw new PassalongError("say why you are passing: pass a note with taken=false");
-  return api.ack(await resolveId(id), taken, note.trim());
-}
-
 /** Mark notifications seen. No ids means everything unread. */
 export const seen = (ids = []) => api.markRead(ids);
 
@@ -1088,25 +993,20 @@ export function summary(g) {
 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 { guide } = await resolve(id, { peek: true });
   const next = { ...guide, meta: { ...guide.meta, status } };
   // The server first. Saved the other way round, a refusal left the local copy saying what the
   // server had just refused — a teammate's `ready` on someone else's task read as done here.
-  if (api.loggedIn() && guide.meta.url) await api.setStatus(id, status);
-  store.save(next);
+  await api.setStatus(id, status);
   return next;
 }
 
 /**
- * Move a task from Draft to Ready: a person has read it and an agent may take it.
- *
- * Only tasks. Every other kind is published the moment it is shared, so "ready" on one would
- * either do nothing or reopen something archived under a name that does not say so.
+ * Move a guide from Draft to Ready: a person has read it, and whoever it is for may take it now.
+ * Every kind: a handoff or bug is a draft until somebody says so, as a task always was.
  */
 export async function ready(id) {
-  const { guide } = await resolve(id);
-  if (guide.meta.kind !== "task")
-    throw new PassalongError(`${guide.meta.id || id} is not a task — ready is for tasks in Draft`);
+  const { guide } = await resolve(id, { peek: true });
   if (guide.meta.status !== "draft")
     throw new PassalongError(`${guide.meta.id} is not in Draft (status: ${guide.meta.status})`);
   return setStatus(guide.meta.id, "published");
@@ -1162,8 +1062,7 @@ export async function planTasks(steps, { cwd = process.cwd() } = {}) {
 /** What an agent started by `work()` is told. The task itself goes in too, so it cannot start blind. */
 export function workPrompt(t) {
   return [
-    `You hold passalong task ${t.id}, and no other agent can take it while you do.`,
-    `It is written to ${t.path}; here it is:`,
+    `You hold passalong task ${t.id}, and no other agent can take it while you do. Here it is:`,
     "",
     t.markdown.trim(),
     "",
@@ -1216,7 +1115,7 @@ export async function work({
     const run = spawnSync(command, [...args, workPrompt(t)], {
       cwd,
       stdio: "inherit",
-      env: { ...process.env, PASSALONG_TASK: t.id, PASSALONG_TASK_PATH: t.path },
+      env: { ...process.env, PASSALONG_TASK: t.id },
     });
     const state = (await tasks()).find((x) => x.id === t.id)?.state;
     if (state !== "review")
@@ -1233,14 +1132,14 @@ export async function work({
 }
 
 /**
- * Make every task you wrote that is still in Draft ready, and return their ids. For the moment a
- * planner has written several and you have read them all. Only your own: moving a task into the
- * queue is its author's call.
+ * Make every guide you wrote that is still in Draft ready, and return their ids. For the moment a
+ * planner has written several and you have read them all. Only your own: sending a guide on is its
+ * author's call.
  */
 export async function readyDrafts() {
-  const drafts = (await tasks()).filter((t) => t.mine && t.state === "draft");
-  for (const t of drafts) await ready(t.id);
-  return drafts.map((t) => t.id);
+  const drafts = (await list("", { scope: "mine" })).filter((g) => g.status === "draft");
+  for (const g of drafts) await ready(g.id);
+  return drafts.map((g) => g.id);
 }
 
 export async function remove(id) {
@@ -1255,14 +1154,49 @@ export async function remove(id) {
   store.remove(id);
 }
 
-/** Write every local guide to a directory as plain markdown. Returns the paths written. */
-export function exportAll(dir) {
+/**
+ * Write every guide to a directory as plain markdown: signed in, every one the server lets this
+ * account read, and the local store's own besides. Returns the paths written.
+ */
+export async 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);
+  const paths = new Map();
+  if (api.loggedIn()) {
+    let after = "";
+    do {
+      const page = await api.exportPage(after);
+      for (const g of page.guides) paths.set(g.id, g.markdown);
+      after = page.next;
+    } while (after);
+  }
+  for (const g of store.list()) if (!paths.has(g.meta.id)) paths.set(g.meta.id, serialize(g));
+  return [...paths].map(([id, md]) => {
+    const p = join(dir, `${id}.md`);
+    writeFileSync(p, md);
+    return p;
+  });
+}
+
+/**
+ * Once per machine, signed in: drop the local copies the server says it holds. They were written
+ * by every share, pull and take before `keep()`, and nothing ever removed one. What the server
+ * does not return — shared while signed out, or from another account — is left where it is.
+ */
+export async function tidy() {
+  if (!api.loggedIn() || store.readConfig().tidied) return 0;
+  const local = new Set(store.list().map((g) => g.meta.id));
+  let removed = 0;
+  let after = "";
+  while (local.size) {
+    const page = await api.exportPage(after);
+    for (const g of page.guides)
+      if (local.delete(g.id)) {
+        store.remove(g.id);
+        removed++;
+      }
+    after = page.next;
+    if (!after) break;
   }
-  return paths;
+  store.writeConfig({ tidied: true });
+  return removed;
 }