bikeshed-now 0.12.0 → 0.15.0

package/README.md

@@ -38,18 +38,28 @@ be using the same one: revoke it at `/account` once nothing needs it.
 bikeshed publish proposal.md --title "Storage migration"
 # published storage-migration v1 — https://bikeshed.now/d/storage-migration
 
-# Somebody highlights a sentence and says what is wrong with it.
+# Somebody highlights a sentence and says what is wrong with it. Wait for it:
+# the cursor comes from `publish --json`, and every `changes` prints the next one.
+bikeshed changes storage-migration --since <cursor> --wait
 bikeshed comments storage-migration
 
 # Fix that sentence, say what you changed in its thread, then publish the
 # revision. Reply first: a thread belongs to the version it was written on.
 bikeshed reply storage-migration <thread> "Rewritten to describe the dual-write period."
-bikeshed update storage-migration proposal.md
+bikeshed resolve storage-migration <thread>   # closes it, with a note saying you did
+bikeshed update storage-migration proposal.md --base v1   # refused if somebody published since
 
 # Given "Can suggest" rather than "Can edit"? Propose the change instead, for a
 # person to accept or reject.
 bikeshed suggest storage-migration "a single weekend" --with "two weekends"
 
+# Own the document, or can approve on it? Decide somebody's suggestions: an
+# accept goes into the draft, a rejection carries the reason its author is sent,
+# and commit publishes the draft as one version.
+bikeshed accept storage-migration <thread>
+bikeshed reject storage-migration <thread> --reason "Already in section 3."
+bikeshed commit storage-migration
+
 # Something nobody has raised yet? Start a thread on the passage it is about.
 bikeshed comment storage-migration "a single weekend" --body "Is the dual-write fortnight in this?"
 ```
@@ -69,8 +79,28 @@ bikeshed publish platform.md --id 01-platform
 # published 01-platform v1 — https://bikeshed.now/d/01-platform
 ```
 
-If the id is taken, the document is still published, at the id plus a few
-random characters, and the CLI says so on stderr.
+`publish` says where it filed the document and who can read it there.
+`bikeshed folders` counts who can read each folder, and `bikeshed folder <id>`
+names them: filing a document in a folder shares it with all of them, and
+nobody is emailed.
+
+Ids are shared by the whole deployment and never change, so choose one every
+time: put the date first on something time-bound
+(`2026-10-09-storage-migration-review`), and the project on something that
+lives on (`billing-storage-migration`, not `migration`). If the id is taken, the
+document is still published, at the id plus a few random characters, and the
+CLI says so on stderr.
+
+`bikeshed open <link>` opens a document in your browser, an unlisted one's key
+included. It opens the browser on the machine that runs it, so an agent in CI
+or a container should hand you the link instead.
+
+A rename changes the title and leaves the address alone, so links already sent
+keep working:
+
+```bash
+bikeshed rename 01-platform Platform review, second pass
+```
 
 Wherever a command takes an id, it also takes the link you were sent. An
 unlisted document you are not a member of needs the link, because its key is in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bikeshed-now",
-  "version": "0.12.0",
+  "version": "0.15.0",
   "license": "Apache-2.0",
   "type": "module",
   "description": "Publish and revise documents on a Bikeshed deployment from the terminal.",

package/src/client.mjs

@@ -95,7 +95,7 @@ export async function callTool(origin, token, name, args = {}) {
  * with `update`, as a new version of that document, with `k` for an unlisted
  * one.
  */
-export async function uploadFile(origin, token, path, { title, folder, id, update, k } = {}) {
+export async function uploadFile(origin, token, path, { title, folder, id, update, k, base } = {}) {
   const bytes = readFileSync(path);
   const params = new URLSearchParams({ filename: basename(path) });
   if (title) params.set("title", title);
@@ -103,6 +103,7 @@ export async function uploadFile(origin, token, path, { title, folder, id, updat
   if (id) params.set("id", id);
   if (update) params.set("update", update);
   if (k) params.set("k", k);
+  if (base) params.set("baseVersion", base);
 
   const res = await fetch(`${origin}/publish?${params}`, {
     method: "POST",

package/src/index.mjs

@@ -53,22 +53,40 @@ const USAGE = `bikeshed ${VERSION} — publish and revise documents
   bikeshed lineage <id>                what it was forked from; for its owner, its forks
   bikeshed get <id>                    print a document's source
   bikeshed comments <id>               unresolved feedback, with its anchored text
+                                       (--version <v> for an earlier version's)
+  bikeshed changes <id> --since <cursor|last|all>
+                                       what happened since a cursor; --wait to
+                                       keep checking until something does
   bikeshed comment <id> <text> --body <comment>
                                        start a thread on a passage
   bikeshed reply <id> <thread> <text>  reply in a thread
+  bikeshed resolve <id> <thread>       close a thread once its point is dealt with
+  bikeshed reopen <id> <thread>        open a resolved thread again
   bikeshed suggest <id> <text> --with <new text>
                                        propose new text for a passage, for a
                                        person to accept or reject (--delete to
                                        propose removing it)
+  bikeshed revise <id> <thread> --with <new text>
+                                       change your suggestion before it is
+                                       decided; what it said before is kept
+  bikeshed withdraw <id> <thread>      take back your suggestion before it is
+                                       decided; its thread stays
+  bikeshed accept <id> <thread>        accept a suggestion, as its owner or an
+                                       approver: the change goes into the draft
+  bikeshed reject <id> <thread>        decline a suggestion, as its owner or an
+                                       approver (--reason <why>)
+  bikeshed commit <id>                 publish the draft as the next version
   bikeshed open <id>                   open it in a browser
 
   Where a command takes <id> it also takes the link you were sent. An unlisted
   document you are not a member of needs the link: its key is in it.
 
 Organising
-  bikeshed folders                     the folder tree, with ids
+  bikeshed folders                     the folder tree, with ids and readers
+  bikeshed folder <id>                 who can read a folder, and so what is in it
   bikeshed mkdir <name> [--parent <id>]  create a folder
   bikeshed mv <id> <folder|root>       move a document
+  bikeshed rename <id> <title>         change a document's title; its address stays
 
 Skills
   bikeshed skills                      skills this deployment publishes
@@ -93,15 +111,27 @@ Options
   --title <text>         title for publish or fork (fork default: the original's)
   --id <id>              with publish: the address, /d/<id> (default: from the title)
   --folder <id>          destination folder for publish or fork
-  --version <v>          with fork: the version to copy (default: current);
-                         on its own, which version of bikeshed this is
+  --version <v>          with fork: the version to copy; with comments: the
+                         version to read (default: current); on its own,
+                         which version of bikeshed this is
   --parent <id>          parent folder for mkdir
   --limit <n>            with list: rows per page (default 20, max 50)
   --cursor <id>          with list: the page after the one that printed it
+  --since <cursor>       with changes: a cursor publish, fork, get --json or
+                         changes printed; "last" where this sign-in left off;
+                         or "all"
+  --wait                 with changes: keep checking until something happens
+  --interval <s>         with changes --wait: seconds between checks (default
+                         60, at least 30)
+  --timeout <s>          with changes --wait: give up after this long (default
+                         3600), exit 3, and print the cursor to resume from
+  --base <v>             with update: the version you revised; refused if
+                         somebody has published since
   --all                  with list: every page; with comments: resolved too
-  --with <text>          with suggest: what the passage should say instead
-  --delete               with suggest: propose deleting the passage
-  --note <text>          with suggest: why, for whoever decides
+  --with <text>          with suggest or revise: what the passage should say instead
+  --delete               with suggest or revise: propose deleting the passage
+  --note <text>          with suggest or revise: why, for whoever decides
+  --reason <text>        with reject: why, for the suggestion's author
   --prefix <text>        with suggest: words just before a passage that repeats
   --suffix <text>        with suggest: words just after it
   --watch                with publish/update: republish on every save
@@ -433,9 +463,11 @@ async function publish(flags, [path]) {
     }
     // The address is in the human line already; `--json` carried only the id, so
     // anything reading it had to know how to build a URL out of a docId.
-    out(flags.json, { ...result, url: result.url ?? `${origin}/d/${result.docId}` }, () =>
-      console.log(`published ${result.docId} ${result.versionId} — ${origin}/d/${result.docId}`),
-    );
+    out(flags.json, { ...result, url: result.url ?? `${origin}/d/${result.docId}` }, () => {
+      console.log(`published ${result.docId} ${result.versionId} — ${origin}/d/${result.docId}`);
+      const where = describeAccess(result);
+      if (where) console.log(where);
+    });
     return result;
   };
 
@@ -460,9 +492,16 @@ async function update(flags, [ref, path]) {
     const bytes = readFileSync(file);
     // An archive goes up as bytes, to the one endpoint that takes them. Read as
     // text, every byte above 0x7f in it would become U+FFFD on the way.
+    // --base: the version this was revised from, so an update over somebody's
+    // newer save is refused instead of replacing it (SPEC §19).
+    const base = typeof flags.base === "string" && flags.base ? flags.base : undefined;
     const result = isArchive(file, bytes)
-      ? await uploadFile(origin, token, file, { update: id, k: doc.k })
-      : await callTool(origin, token, "update_document", { ...doc, content: bytes.toString("utf8") });
+      ? await uploadFile(origin, token, file, { update: id, k: doc.k, base })
+      : await callTool(origin, token, "update_document", {
+          ...doc,
+          content: bytes.toString("utf8"),
+          ...(base ? { baseVersion: base } : {}),
+        });
     out(flags.json, { ...result, url: result.url ?? `${origin}/d/${id}` }, () =>
       console.log(
         result.deduped
@@ -506,6 +545,9 @@ async function comments(flags, [ref]) {
   const { origin, token } = resolveAuth(flags);
   const result = await callTool(origin, token, "get_comments", {
     ...docArgs(ref),
+    // Threads belong to the version they were opened on; a version in a link
+    // is not taken as a request for one, only the flag is.
+    ...(typeof flags.version === "string" ? { version: flags.version } : {}),
     includeResolved: Boolean(flags.all),
   });
   out(flags.json, result, () => {
@@ -518,11 +560,14 @@ async function comments(flags, [ref]) {
       // which passage to change without opening the document.
       console.log(`\n── ${thread.threadId}${thread.section ? `  (${thread.section})` : ""}`);
       if (thread.quote) console.log(`   “${thread.quote}”`);
-      // A suggested edit says what the passage would become, and whether a
-      // person has decided it yet (SPEC §22).
+      // A suggested edit says what the passage would become, whether it is
+      // still open, and what its author proposed before changing it (SPEC §22).
       if (thread.suggestion) {
-        const change = thread.suggestion.replacement === "" ? "(delete it)" : `“${thread.suggestion.replacement}”`;
-        console.log(`   → ${change}  [${thread.suggestion.state}]`);
+        const said = (text) => (text === "" ? "(delete it)" : `“${text}”`);
+        console.log(`   → ${said(thread.suggestion.replacement)}  [${thread.suggestion.state}]`);
+        for (const earlier of thread.suggestion.revisions ?? []) {
+          console.log(`     was ${said(earlier.replacement)}${earlier.note ? `  (${earlier.note})` : ""}`);
+        }
       }
       for (const comment of thread.comments) {
         const via = comment.via && comment.via !== "web" ? ` [via ${comment.via}]` : "";
@@ -568,6 +613,27 @@ async function reply(flags, [ref, threadId, ...rest]) {
   out(flags.json, result, () => console.log(`replied in ${threadId}`));
 }
 
+/**
+ * Close a thread on the current version, or open it again. Either leaves a
+ * note in the thread saying who did it and through what, which is how the
+ * person who raised the point hears (SPEC §19).
+ */
+// `resolve` alone is node:path's, imported above.
+async function resolveThread(flags, args) {
+  await setResolved(flags, args, "resolve");
+}
+
+async function reopenThread(flags, args) {
+  await setResolved(flags, args, "reopen");
+}
+
+async function setResolved(flags, [ref, threadId, ...rest], verb) {
+  if (!ref || !threadId || rest.length) fail(`usage: bikeshed ${verb} <id> <thread>`);
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, `${verb}_thread`, { ...docArgs(ref), threadId });
+  out(flags.json, result, () => console.log(`${verb === "resolve" ? "resolved" : "reopened"} ${threadId}`));
+}
+
 /**
  * Propose new text for one passage of a document's current version. The
  * passage is quoted as a reader sees it, which is how `comments` prints it, so
@@ -577,16 +643,12 @@ async function suggest(flags, [ref, ...rest]) {
   const exact = rest.join(" ");
   const usage = "usage: bikeshed suggest <id> <text> (--with <new text> | --delete) [--note <why>]";
   if (!ref || !exact) fail(usage);
-  const replacing = typeof flags.with === "string";
-  if (replacing === Boolean(flags.delete)) fail(usage);
-  // An empty --with is what an unset shell variable sends; deleting a passage
-  // has to be asked for by name.
-  if (replacing && flags.with === "") fail("an empty --with would delete the passage; say --delete if you mean that");
+  const replacement = replacementFrom(flags, usage);
   const { origin, token } = resolveAuth(flags);
   const result = await callTool(origin, token, "suggest_edit", {
     ...docArgs(ref),
     exact,
-    replacement: replacing ? flags.with : "",
+    replacement,
     ...(typeof flags.note === "string" ? { note: flags.note } : {}),
     ...(typeof flags.prefix === "string" ? { prefix: flags.prefix } : {}),
     ...(typeof flags.suffix === "string" ? { suffix: flags.suffix } : {}),
@@ -596,6 +658,82 @@ async function suggest(flags, [ref, ...rest]) {
   );
 }
 
+/** The replacement `suggest` and `revise` were given: --with, or --delete by name. */
+function replacementFrom(flags, usage) {
+  const replacing = typeof flags.with === "string";
+  if (replacing === Boolean(flags.delete)) fail(usage);
+  // An empty --with is what an unset shell variable sends; deleting a passage
+  // has to be asked for by name.
+  if (replacing && flags.with === "") fail("an empty --with would delete the passage; say --delete if you mean that");
+  return replacing ? flags.with : "";
+}
+
+/**
+ * Change the text of a suggestion of yours that nobody has decided yet. What
+ * it said before is kept, for whoever decides (SPEC §22).
+ */
+async function revise(flags, [ref, threadId, ...rest]) {
+  const usage = "usage: bikeshed revise <id> <thread> (--with <new text> | --delete) [--note <why>]";
+  if (!ref || !threadId || rest.length) fail(usage);
+  const replacement = replacementFrom(flags, usage);
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "revise_suggestion", {
+    ...docArgs(ref),
+    threadId,
+    replacement,
+    ...(typeof flags.note === "string" ? { note: flags.note } : {}),
+  });
+  out(flags.json, result, () => console.log(`changed ${threadId}; what it said before is kept`));
+}
+
+/**
+ * Accept a suggestion, as the document's owner or an approver. The change is
+ * made in the draft, where the decisions of a review gather until `commit`
+ * publishes them as one version (SPEC §22).
+ */
+async function accept(flags, [ref, threadId, ...rest]) {
+  if (!ref || !threadId || rest.length) fail("usage: bikeshed accept <id> <thread>");
+  const { origin, token } = resolveAuth(flags);
+  // Deciding takes a real role on the document, never a link, so only the id is sent.
+  const result = await callTool(origin, token, "accept_suggestion", { id: docArgs(ref).id, threadId });
+  out(flags.json, result, () => console.log(`accepted ${threadId}; the change is in the draft — \`bikeshed commit\` publishes it`));
+}
+
+/** Publish the draft as the document's next version, as "Save as new version" does in the app. */
+async function commit(flags, [ref, ...rest]) {
+  if (!ref || rest.length) fail("usage: bikeshed commit <id>");
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "commit_draft", { id: docArgs(ref).id });
+  out(flags.json, result, () =>
+    console.log(result.deduped ? `nothing new: the draft is ${result.versionId} already` : `published ${result.versionId}`),
+  );
+}
+
+/**
+ * Decline a suggestion, as the document's owner or an approver. The passage
+ * stays as it is and the thread closes with a note giving the reason, which
+ * its author is sent (SPEC §22).
+ */
+async function reject(flags, [ref, threadId, ...rest]) {
+  if (!ref || !threadId || rest.length) fail("usage: bikeshed reject <id> <thread> [--reason <why>]");
+  const { origin, token } = resolveAuth(flags);
+  // Deciding takes a real role on the document, never a link, so only the id is sent.
+  const result = await callTool(origin, token, "reject_suggestion", {
+    id: docArgs(ref).id,
+    threadId,
+    ...(typeof flags.reason === "string" ? { reason: flags.reason } : {}),
+  });
+  out(flags.json, result, () => console.log(`rejected ${threadId}`));
+}
+
+/** Take back a suggestion of yours that nobody has decided yet; its thread stays. */
+async function withdraw(flags, [ref, threadId, ...rest]) {
+  if (!ref || !threadId || rest.length) fail("usage: bikeshed withdraw <id> <thread>");
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "withdraw_suggestion", { ...docArgs(ref), threadId });
+  out(flags.json, result, () => console.log(`withdrew ${threadId}`));
+}
+
 async function folders(flags) {
   const { origin, token } = resolveAuth(flags);
   const result = await callTool(origin, token, "list_folders", {});
@@ -611,7 +749,9 @@ async function folders(flags) {
       const depth = folder.path.split("/").length - 1;
       const label = `${"  ".repeat(depth)}${folder.name}`;
       const note = folder.canWrite ? "" : "  (read-only)";
-      console.log(`${label.padEnd(40)} ${folder.id}${note}`);
+      // Filing a document here shares it with everyone counted, and emails nobody.
+      const readers = typeof folder.readers === "number" ? `  ${folder.readers} can read` : "";
+      console.log(`${label.padEnd(40)} ${folder.id}${readers}${note}`);
     }
     if (result.truncated) {
       console.log("\nThere are more folders than this listing shows.");
@@ -619,6 +759,96 @@ async function folders(flags) {
   });
 }
 
+/**
+ * Where a published document is filed and who can read it there, from what the
+ * server read after the write, for a person to be told. Empty for a deployment
+ * too old to say.
+ */
+function describeAccess(result) {
+  const access = result.access;
+  if (!access) return "";
+  const where = result.filedIn ? `filed in ${result.filedIn.path}` : "at the root";
+  const who = access.readers === 1 ? "only you can read it" : `${access.readers} people can read it`;
+  const also = access.alsoReadableBy ? `, and ${access.alsoReadableBy}` : "";
+  return `${where}: ${who}${also}`;
+}
+
+/** Who can read one folder: and so who can read anything filed in it. */
+async function folder(flags, [id]) {
+  if (!id) fail("usage: bikeshed folder <id>");
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "get_folder", { id });
+  out(flags.json, result, () => {
+    console.log(`${result.path}  ${result.id}${result.canWrite ? "" : "  (read-only)"}`);
+    console.log(`${result.readers} can read it${result.readers === 1 ? " (only you)" : ""}:`);
+    for (const person of result.people) console.log(`  ${person}`);
+    if (result.morePeople > 0) console.log(`  and ${result.morePeople} more`);
+    if (result.teams.length) console.log(`teams: ${result.teams.join(", ")}`);
+    console.log(`can edit: ${[...result.editors, ...(result.moreEditors ? [`and ${result.moreEditors} more`] : [])].join(", ")}`);
+  });
+}
+
+/** Exit status when `changes --wait` gives up: distinct from 1, an error. */
+const WAIT_TIMED_OUT = 3;
+/** The shortest wait between checks: each one reads the log and the document. */
+const MIN_INTERVAL_S = 30;
+
+/**
+ * What happened on a document since a cursor (SPEC §19, ADR 0016).
+ *
+ * `--since` is required: a check that starts from nowhere in particular
+ * reports nothing, and nothing reads as nothing happened. Every page is read
+ * before anything is printed, and the cursor printed last is the one to pass
+ * next time: replace whatever you held with it.
+ *
+ * `--wait` keeps checking until something happens, then prints it and exits 0.
+ * A harness that wakes an agent when a background command ends (Claude Code
+ * does) gets watching from one command. On timeout it exits 3 and still prints
+ * the cursor, so the next wait resumes rather than restarts.
+ */
+async function changes(flags, [ref]) {
+  const usage = "usage: bikeshed changes <id> --since <cursor|last|all> [--wait] [--interval <s>] [--timeout <s>]";
+  if (!ref) fail(usage);
+  if (typeof flags.since !== "string" || !flags.since) {
+    fail(`${usage}\n--since is required: a cursor that publish, fork, get --json or changes printed; "last", where this sign-in left off; or "all"`);
+  }
+  const interval = Math.max(MIN_INTERVAL_S, flags.interval === undefined ? 60 : Number(flags.interval) || 0);
+  const timeout = flags.timeout === undefined ? 3600 : Number(flags.timeout);
+  if (!Number.isFinite(timeout) || timeout < 0) fail(usage);
+  const { origin, token } = resolveAuth(flags);
+  const doc = docArgs(ref);
+  const started = Date.now();
+  let since = flags.since;
+  const events = [];
+  for (;;) {
+    const result = await callTool(origin, token, "get_changes", { ...doc, since });
+    since = result.cursor;
+    events.push(...result.events);
+    if (result.more) continue;
+    const waitFor = Math.max(interval, Number(result.retryAfter) || 0);
+    if (!flags.wait || events.length > 0) return printChanges(flags, { ...result, events });
+    if ((Date.now() - started) / 1000 + waitFor > timeout) {
+      process.exitCode = WAIT_TIMED_OUT;
+      return printChanges(flags, { ...result, events, timedOut: true });
+    }
+    await new Promise((r) => setTimeout(r, waitFor * 1000));
+  }
+}
+
+function printChanges(flags, result) {
+  out(flags.json, result, () => {
+    if (result.timedOut) console.log("nothing new before the timeout");
+    for (const e of result.events) {
+      const quote = e.quote ? ` “${e.quote}”` : "";
+      const words = e.body ? `: ${e.body}` : e.replacement !== undefined ? ` → “${e.replacement}”` : "";
+      const via = e.channel && e.channel !== "web" ? ` [via ${e.channel}]` : "";
+      console.log(`${e.at}  ${e.type}  ${e.by ?? ""}${via}${e.threadId ? `  (${e.threadId})` : ""}${quote}${words}`);
+    }
+    if (result.needsReply?.length) console.log(`waiting on a reply: ${result.needsReply.join(", ")}`);
+    console.log(`next: --since ${result.cursor}`);
+  });
+}
+
 /**
  * Your own copy of a document you can read. The original's author sees that it
  * was forked — a count, never who — and the fork records where it came from,
@@ -706,13 +936,30 @@ async function mv(flags, [id, dest]) {
    */
   if (!id || !dest) fail("usage: bikeshed mv <id> <folder|root>");
   const { origin, token } = resolveAuth(flags);
-  const args = dest === "root" ? { id } : { id, folder: dest };
+  // Moving is an editor's act, and a link's key only lets somebody read, so
+  // only the id goes along.
+  const doc = docArgs(id).id;
+  const args = dest === "root" ? { id: doc } : { id: doc, folder: dest };
   const result = await callTool(origin, token, "move_document", args);
   out(flags.json, result, () =>
-    console.log(result.folder ? `moved ${id} into ${result.folder}` : `moved ${id} to the root`),
+    console.log(result.folder ? `moved ${doc} into ${result.folder}` : `moved ${doc} to the root`),
   );
 }
 
+/**
+ * Give a document a new title. Its address is its id, which never changes, so
+ * every link already sent keeps working (SPEC §4). The title is the rest of the
+ * line, so it needs no quotes.
+ */
+async function rename(flags, [ref, ...rest]) {
+  const title = rest.join(" ").trim();
+  if (!ref || !title) fail("usage: bikeshed rename <id> <title>");
+  const { origin, token } = resolveAuth(flags);
+  // Renaming takes no link key, as in the workspace list: only the id is sent.
+  const result = await callTool(origin, token, "rename_document", { id: docArgs(ref).id, title });
+  out(flags.json, result, () => console.log(`renamed ${result.id} to “${result.title}”`));
+}
+
 /**
  * Skills are instructions, not code, and they are fetched from the DEPLOYMENT
  * rather than bundled with this CLI on purpose: a deployment running an older
@@ -757,10 +1004,13 @@ async function skillsCommand(flags, [sub, dir]) {
   });
 }
 
-async function open(flags, [id]) {
-  if (!id) fail("usage: bikeshed open <id>");
+async function open(flags, [ref]) {
+  if (!ref) fail("usage: bikeshed open <id>");
   const { origin } = resolveAuth(flags);
-  const url = `${origin}/d/${id}`;
+  // An unlisted document opens only with its key, and the link is the one place
+  // the key lives, so a link keeps it.
+  const { id, k } = docArgs(ref);
+  const url = `${origin}/d/${encodeURIComponent(id)}${k ? `?k=${encodeURIComponent(k)}` : ""}`;
   // Best effort, and the address is printed either way. This used to spawn
   // `start`, which is a cmd.exe builtin rather than a program, so on Windows
   // the spawn failed and, with nothing listening for the error, crashed.
@@ -800,13 +1050,23 @@ const COMMANDS = {
   lineage,
   get,
   comments,
+  changes,
   comment,
   reply,
+  resolve: resolveThread,
+  reopen: reopenThread,
   suggest,
+  revise,
+  withdraw,
+  accept,
+  reject,
+  commit,
   open,
   folders,
+  folder,
   mkdir,
   mv,
+  rename,
   skills: skillsCommand,
 };
 
@@ -837,9 +1097,15 @@ async function main() {
       paste: { type: "boolean", default: false },
       "no-browser": { type: "boolean", default: false },
       note: { type: "string" },
+      reason: { type: "string" },
       body: { type: "string" },
       prefix: { type: "string" },
       suffix: { type: "string" },
+      since: { type: "string" },
+      wait: { type: "boolean", default: false },
+      interval: { type: "string" },
+      timeout: { type: "string" },
+      base: { type: "string" },
     },
   });