passalong 0.17.0 → 0.19.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 → id + link, Ready; --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 Ready when shared (or a draft, with
+`status: draft`, until a person runs `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

@@ -6,26 +6,25 @@
 //     handed to whoever pulls or starts that guide
 //     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 task "<what needs doing>"  write a task for an agent; Ready at once
+//   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 reopen <id> <why>   finished work isn't right: back to To do, 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 +34,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 +63,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 +165,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 +303,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 +311,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,17 +329,15 @@ 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);
     const id = guide.meta.id;
     console.log(id);
     const target = guide.meta.target_context;
-    console.error(`task "${guide.meta.title}" is in Draft${target ? ` for ${target}` : " (no repo)"}`);
+    console.error(`task "${guide.meta.title}" is Ready${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() {
@@ -442,16 +382,25 @@ const commands = {
     if (n) console.error("review them with: passalong tasks");
   },
 
-  async approve(f) {
-    const id = f._[0] || die("usage: passalong approve <id>");
-    await passalong.approveTask(id).catch((e) => die(e.message));
-    console.error(`${id} is done`);
+  // Nothing waits for approval now (docs/REVIEW.md): finishing is final. Kept so a script that
+  // calls it is told, not refused.
+  async approve() {
+    console.error(
+      "nothing to approve: finished work is already Done. If it isn't right: passalong reopen <id> <why>",
+    );
+  },
+
+  /** Finished work back to To do, with why at its top; whoever finished it is told. */
+  async reopen(f) {
+    const id = f._[0] || die("usage: passalong reopen <id> <why>");
+    const why = f._.slice(1).join(" ");
+    if (!why) die("say why: passalong reopen <id> <what is wrong>");
+    await passalong.reopen(id, why).catch((e) => die(e.message));
+    console.error(`${id} is back in To do — whoever takes it next reads why`);
   },
 
   async reject(f) {
-    const id = f._[0] || die("usage: passalong reject <id> <why>");
-    await passalong.rejectTask(id, f._.slice(1).join(" ")).catch((e) => die(e.message));
-    console.error(`${id} is back in Ready — the next agent reads why`);
+    return commands.reopen(f);
   },
 
   async release(f) {
@@ -480,31 +429,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 +560,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 +591,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 +601,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 +640,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 +694,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 +728,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 +784,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 +1054,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.19.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,12 @@ 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). It is Ready and has reached whoever it is for. 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,13 @@ 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 } });
+export const reopen = (id, why) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/reopen`, { 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

@@ -497,7 +497,9 @@ export function stamp(guide, defaults = {}) {
   const meta = { ...guide.meta };
   if (!meta.id) meta.id = newId();
   if (!meta.created) meta.created = new Date().toISOString();
-  if (!meta.status) meta.status = "draft";
+  // Ready unless whoever wrote it said draft: a guide sent to someone is meant to reach them, and
+  // drafts were where addressed work sat forgotten (every draft in production on 2026-10-15).
+  if (!meta.status) meta.status = "published";
   for (const [k, v] of Object.entries(defaults))
     if (meta[k] === undefined || meta[k] === "") meta[k] = v;
   return { meta, body: guide.body };
@@ -616,7 +618,7 @@ export function template(meta = {}) {
       summary: "",
       author: "",
       source_context: "",
-      status: "draft",
+      status: "published",
       stack_assumptions: [],
       tags: [],
       ...meta,
@@ -654,7 +656,7 @@ function bugTemplate(meta = {}) {
       kind: "bug",
       author: "",
       source_context: "",
-      status: "draft",
+      status: "published",
       severity: "s3",
       stack_assumptions: [],
       tags: ["bug"],
@@ -696,7 +698,7 @@ function taskTemplate(meta = {}) {
       author: "",
       source_context: "",
       target_context: "",
-      status: "draft",
+      status: "published",
       stack_assumptions: [],
       tags: [],
       ...meta,