@coderook/cli 0.31.3 → 0.31.4

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "coderook",
   "displayName": "CodeRook",
   "description": "Save, browse and restore whole-snapshot versions of a project on CodeRook, from Claude Code.",
-  "version": "0.31.3",
+  "version": "0.31.4",
   "author": {
     "name": "ACCA Gaming Productions",
     "url": "https://coderook.com"

package/dist/cli/src/cli.js

@@ -39,6 +39,7 @@ const worktree_js_1 = require("../../desktop-app/src/main/worktree.js");
 const rules_js_1 = require("../../desktop-app/src/main/rules.js");
 const upload_js_1 = require("../../desktop-app/src/main/upload.js");
 const download_js_1 = require("../../desktop-app/src/main/download.js");
+const safe_path_js_1 = require("../../desktop-app/src/shared/safe_path.js");
 const faults_js_1 = require("../../desktop-app/src/main/faults.js");
 const version_commands_js_1 = require("./version_commands.js");
 const identify_js_1 = require("../../desktop-app/src/main/identify.js");
@@ -1477,7 +1478,19 @@ async function commandUnbundle(parsed) {
         return 1;
     }
     const manifest = await (0, cbx_js_1.readManifest)(node_path_1.default.resolve(source));
-    const destination = node_path_1.default.resolve(parsed.positional[1] ?? manifest.source_name);
+    /*
+      The bundle's own name, never its path. `source_name` comes from the file
+      being opened, and taken whole it could be `/home/you/.ssh` or `C:\Users` —
+      and the folder it names is deleted and replaced. Only the last name
+      survives, into the current folder, and only if it is a plain name.
+    */
+    const suggested = node_path_1.default.posix.basename((manifest.source_name ?? "").replace(/\\/g, "/"));
+    const plainName = suggested && !(0, safe_path_js_1.whyUnsafe)(suggested) && !/^[.]+$/.test(suggested) && !/[:]/.test(suggested);
+    if (!parsed.positional[1] && !plainName) {
+        console.error(red("That bundle does not name a usable folder. Try: cbx unbundle <file.cbx> <folder>"));
+        return 1;
+    }
+    const destination = node_path_1.default.resolve(parsed.positional[1] ?? suggested);
     const line = progressLine();
     const result = await (0, cbx_js_1.unpackBundle)(node_path_1.default.resolve(source), destination, (progress) => {
         line(`  ${track(progress.percent)} ${String(progress.percent).padStart(3)}%  ` +

package/dist/cli/src/git_remote.js

@@ -109,6 +109,7 @@ exports.main = main;
  * where the original branched.
  */
 const node_child_process_1 = require("node:child_process");
+const safe_path_js_1 = require("../../desktop-app/src/shared/safe_path.js");
 const promises_1 = require("node:fs/promises");
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -136,6 +137,17 @@ class ImportFailed extends Error {
 class AlreadyReported extends Error {
 }
 exports.AlreadyReported = AlreadyReported;
+/**
+ * A name as fast-import may carry it on an author, committer or tagger line.
+ *
+ * Every other line of the stream is built from values the helper made; these
+ * come from what people typed. A newline in a display name ended the line and
+ * began another — any command the stream accepts, a symlink or a ref update
+ * included — and `<` or `>` would end the name early. Each becomes a space.
+ */
+function identity(name) {
+    return name.replace(/[\x00-\x1f\x7f<>]/g, " ").replace(/\s+/g, " ").trim() || "CodeRook";
+}
 /** Everything the helper writes for a person goes to stderr; stdout is protocol. */
 function say(text) {
     node_process_1.default.stderr.write(`${text}\n`);
@@ -808,8 +820,8 @@ depth = null) {
               worse than an obviously synthetic one: it survives being copied into a
               mailing list or a CONTRIBUTORS file.
             */
-            send(`author ${author} <noreply@coderook.com> ${when}`);
-            send(`committer ${author} <noreply@coderook.com> ${when}`);
+            send(`author ${identity(author)} <noreply@coderook.com> ${when}`);
+            send(`committer ${identity(author)} <noreply@coderook.com> ${when}`);
             send(`data ${body.length}`);
             node_process_1.default.stdout.write(body);
             node_process_1.default.stdout.write("\n");
@@ -819,6 +831,13 @@ depth = null) {
                 send(`merge :${extra}`);
             send("deleteall");
             for (const file of files) {
+                /*
+                  Never into git's own directory. Git would refuse to check one out,
+                  but it would sit in the history of every clone; new versions cannot
+                  hold one, and this keeps older ones from carrying it into git.
+                */
+                if (file.path.split("/").some(safe_path_js_1.isGitDirectoryName))
+                    continue;
                 send(`M 100644 :${blobMark.get(file.sha256)} ${(0, git_history_js_1.quotePath)(file.path)}`);
             }
             send("");
@@ -880,9 +899,12 @@ depth = null) {
                 if (mark === undefined)
                     continue;
                 const body = Buffer.from(release.notes || release.name, "utf8");
-                send(`tag ${release.name}`);
+                const tagName = release.name.replace(/[\s~^:?*[\\\x00-\x1f]/g, "-");
+                if (!tagName || tagName.startsWith("-") || tagName.includes(".."))
+                    continue;
+                send(`tag ${tagName}`);
                 send(`from :${mark}`);
-                send(`tagger ${release.releasedBy || "CodeRook"} <noreply@coderook.com> ` +
+                send(`tagger ${identity(release.releasedBy || "CodeRook")} <noreply@coderook.com> ` +
                     `${(0, git_history_js_1.stamp)(release.releasedAt)} +0000`);
                 send(`data ${body.length}`);
                 node_process_1.default.stdout.write(body);

package/dist/desktop-app/src/main/cbx.js

@@ -29,6 +29,7 @@ const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
+const safe_path_js_1 = require("../shared/safe_path.js");
 const node_zlib_1 = require("node:zlib");
 const download_js_1 = require("./download.js");
 const chunking_js_1 = require("../shared/chunking.js");
@@ -343,9 +344,9 @@ async function unpackBundle(source, destination, report) {
         let written = 0;
         let bytes = 0;
         for (const directory of manifest.directories ?? []) {
-            const parts = safeParts(directory);
-            if (parts.length)
-                await (0, promises_1.mkdir)(node_path_1.default.join(staging, ...parts), { recursive: true });
+            if (!directory || directory === ".")
+                continue;
+            await (0, promises_1.mkdir)((0, safe_path_js_1.inside)(staging, directory), { recursive: true });
         }
         for (const record of manifest.files) {
             report?.({
@@ -356,10 +357,8 @@ async function unpackBundle(source, destination, report) {
                 path: record.path,
                 percent: (0, download_js_1.underway)(bytes, totalBytes),
             });
-            const parts = safeParts(record.path);
-            if (!parts.length)
-                throw new Error(`Unsafe path in bundle: ${record.path}`);
-            const full = node_path_1.default.join(staging, ...parts);
+            /* Refuses `..`, absolute paths and git's own directory; see safe_path.ts. */
+            const full = (0, safe_path_js_1.inside)(staging, record.path);
             await (0, promises_1.mkdir)(node_path_1.default.dirname(full), { recursive: true });
             const pieces = [];
             if (record.segments) {
@@ -405,15 +404,6 @@ async function unpackBundle(source, destination, report) {
         await handle.close();
     }
 }
-/** Reject anything that would escape the destination before it is used. */
-function safeParts(relative) {
-    const parts = relative.split(/[\\/]/).filter((part) => part && part !== ".");
-    if (parts.some((part) => part === ".." || part.includes("\0")))
-        return [];
-    if (node_path_1.default.isAbsolute(relative) || /^[a-zA-Z]:/.test(relative))
-        return [];
-    return parts;
-}
 /** Every file under `root`, relative and POSIX-separated, sorted. */
 async function collectEntries(root) {
     const found = [];

package/dist/desktop-app/src/main/download.js

@@ -19,6 +19,7 @@ const promises_1 = require("node:fs/promises");
 const promises_2 = require("node:stream/promises");
 const node_stream_1 = require("node:stream");
 const node_path_1 = __importDefault(require("node:path"));
+const safe_path_js_1 = require("../shared/safe_path.js");
 const identify_js_1 = require("./identify.js");
 const faults_js_1 = require("./faults.js");
 const retry_js_1 = require("./retry.js");
@@ -557,14 +558,18 @@ class Downloader {
                     jobs.push({ kind: "file", file });
                 }
             }
-            /** Refused outright, wherever it appears — inside a pack or beside it. */
-            const safeParts = (where) => {
-                const parts = where.split("/").filter(Boolean);
-                if (parts.some((part) => part === ".." || part.includes("\0"))) {
-                    throw new Error(`That version contains an unsafe path: ${where}`);
+            /*
+              Every path checked before a byte is fetched, so a version carrying one
+              it must not write is refused whole rather than half-written. The check
+              used to refuse `..` alone, which let `.git/config` through to be
+              renamed over a checkout's real one — see shared/safe_path.ts.
+            */
+            for (const file of files) {
+                const reason = (0, safe_path_js_1.whyUnsafe)(file.path);
+                if (reason) {
+                    throw new Error(`That version contains an unsafe path (${reason}): ${file.path}`);
                 }
-                return parts;
-            };
+            }
             const told = { at: 0 };
             const sayProgress = (where) => {
                 const now = Date.now();
@@ -599,7 +604,6 @@ class Downloader {
                 }
                 for (const member of packed.get(packId) ?? []) {
                     this.check();
-                    const memberParts = safeParts(member.path);
                     const offset = member.pack.offset;
                     const length = member.pack.length;
                     if (offset < 0 || length < 0 || offset + length > body.byteLength) {
@@ -610,7 +614,7 @@ class Downloader {
                     if (member.sha256 && digest !== member.sha256) {
                         throw new Error(`${member.path} did not arrive intact`);
                     }
-                    const full = node_path_1.default.join(staging, ...memberParts);
+                    const full = (0, safe_path_js_1.inside)(staging, member.path);
                     await (0, promises_1.mkdir)(node_path_1.default.dirname(full), { recursive: true });
                     await (0, promises_1.writeFile)(full, contents);
                     manifest[member.path] = digest;
@@ -620,8 +624,7 @@ class Downloader {
                 }
             };
             const restoreFile = async (file) => {
-                const parts = safeParts(file.path);
-                const full = node_path_1.default.join(staging, ...parts);
+                const full = (0, safe_path_js_1.inside)(staging, file.path);
                 await (0, promises_1.mkdir)(node_path_1.default.dirname(full), { recursive: true });
                 const digest = await this.fetchInto(repositoryId, versionId, file, full);
                 /*
@@ -721,8 +724,7 @@ class Downloader {
             await (0, promises_1.mkdir)(destination, { recursive: true });
             let placed = 0;
             for (const file of files) {
-                const parts = file.path.split("/").filter(Boolean);
-                const target = node_path_1.default.join(destination, ...parts);
+                const target = (0, safe_path_js_1.inside)(destination, file.path);
                 /*
                   Reconciling leaves alone whatever the incoming version did not
                   change. Writing it anyway would replace an edit in progress with a
@@ -737,7 +739,7 @@ class Downloader {
                 }
                 await (0, promises_1.mkdir)(node_path_1.default.dirname(target), { recursive: true });
                 await (0, promises_1.rm)(target, { recursive: true, force: true });
-                await (0, promises_1.rename)(node_path_1.default.join(staging, ...parts), target);
+                await (0, promises_1.rename)((0, safe_path_js_1.inside)(staging, file.path), target);
                 placed += 1;
                 if (placed === 1)
                     (0, faults_js_1.maybeFail)("get:after-first-file");
@@ -751,10 +753,10 @@ class Downloader {
             for (const [gone, digest] of Object.entries(held ?? {})) {
                 if (manifest[gone] !== undefined)
                     continue;
-                const parts = gone.split("/").filter(Boolean);
-                if (parts.some((part) => part === ".." || part.includes("\0")))
+                /* A path it must not write is not one it may delete either. */
+                if ((0, safe_path_js_1.whyUnsafe)(gone))
                     continue;
-                const target = node_path_1.default.join(destination, ...parts);
+                const target = (0, safe_path_js_1.inside)(destination, gone);
                 /*
                   The version dropped it — but if the bytes here are no longer the
                   ones this folder received, somebody has been working on it, and

package/dist/desktop-app/src/shared/safe_path.js

@@ -0,0 +1,88 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isGitDirectoryName = isGitDirectoryName;
+exports.whyUnsafe = whyUnsafe;
+exports.safeParts = safeParts;
+exports.inside = inside;
+/**
+ * Whether a path from a version may be written into somebody's folder.
+ *
+ * Written after Gitea's CVE-2026-60004, where repository content landed in a
+ * hooks directory and git ran it. Nothing here runs git, but the folder a
+ * project is fetched into very often is a git checkout — and a version holding
+ * `.git/config` would have been written over the real one. A `core.fsmonitor`
+ * line in that file runs a command on the next `git status`, with no
+ * executable bit needed; a plain file named `.git` replaced the whole
+ * directory with a pointer to one the version could also supply.
+ *
+ * The service refuses these paths when a version is saved. They are refused
+ * here as well because this is the side that writes to disk: it must not rest
+ * on the server having been right, having been uncompromised, or having held
+ * the same rules when an older version was saved.
+ *
+ * Shared by every writer — fetching, restoring, unbundling — so there is one
+ * rule, not one per place that happened to think of it.
+ */
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * A name git treats as its own directory.
+ *
+ * The same comparison git's own `verify_path` makes with its NTFS and HFS
+ * protections on: any case, trailing dots and spaces dropped, an alternate
+ * data stream dropped, and the 8.3 short name Windows gives `.git`.
+ */
+function isGitDirectoryName(part) {
+    const name = part.split(":")[0].replace(/[. ]+$/, "").toLowerCase();
+    return name === ".git" || /^git~\d+$/.test(name);
+}
+/** Why this path must not be written, or null when it may. */
+function whyUnsafe(relative) {
+    if (!relative)
+        return "it is empty";
+    if (relative.includes("\0"))
+        return "it contains a NUL character";
+    if (/^[\\/]/.test(relative) || /^[a-zA-Z]:/.test(relative)) {
+        return "it is absolute";
+    }
+    for (const part of relative.split(/[\\/]/)) {
+        if (part === "..")
+            return "it climbs out of the folder";
+        if (isGitDirectoryName(part))
+            return "it writes into git's own directory";
+        /* A stream or a drive-relative name on Windows; refused by the service too. */
+        if (process.platform === "win32" && part.includes(":")) {
+            return "it names a Windows data stream";
+        }
+    }
+    return null;
+}
+/**
+ * The path's parts, or an error naming the path and why.
+ *
+ * Both separators split it, because on Windows either one is a separator:
+ * `a\..\..\x` is three climbs there, whatever a check splitting on `/` saw.
+ */
+function safeParts(relative) {
+    const reason = whyUnsafe(relative);
+    if (reason) {
+        throw new Error(`That version contains an unsafe path (${reason}): ${relative}`);
+    }
+    return relative.split(/[\\/]/).filter((part) => part && part !== ".");
+}
+/**
+ * Where a checked path lands under `root`, confirmed to be inside it.
+ *
+ * The part checks above should make this impossible to fail. It is here so
+ * that the next check somebody forgets does not become the next escape.
+ */
+function inside(root, relative) {
+    const base = node_path_1.default.resolve(root);
+    const full = node_path_1.default.resolve(base, ...safeParts(relative));
+    if (full !== base && !full.startsWith(base + node_path_1.default.sep)) {
+        throw new Error(`That version contains a path outside the folder: ${relative}`);
+    }
+    return full;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coderook/cli",
-  "version": "0.31.3",
+  "version": "0.31.4",
   "description": "CodeRook from the command line, on any operating system",
   "license": "SEE LICENSE IN LICENSE.txt",
   "homepage": "https://coderook.com",

package/skills/coderook/SKILL.md

@@ -1,154 +1,200 @@
----
-name: coderook
-description: Save, browse and restore versions of a project on CodeRook — a version host where every version is a complete snapshot and there is no git to learn. Use when asked to save or submit work to CodeRook, check what has changed, look at a project's versions or files, fetch a project, start or switch a line of work, or resolve a save that landed at the same time as somebody else's.
-allowed-tools: Bash Read
----
-
-# CodeRook
-
-CodeRook stores whole snapshots of a folder. A version names every file the
-project had at that moment, so restoring one never depends on the versions
-around it, and there is no staging area, no branches to rebase and no history
-to rewrite.
-
-Everything here is the `coderook` command line. Run it with Bash.
-
-## Before anything else
-
-`cbx whoami` says who this machine is signed in as. If it refuses, the
-person needs to run `cbx sign-in` themselves — it takes a personal access
-token, so do not attempt it on their behalf.
-
-If the command is not found at all, this machine has the skill but not the
-command line. Either install it once with
-`npm install --global @coderook/cli`, or put `npx -y @coderook/cli` where
-`coderook` appears below — the commands are identical, npx is just slower
-to start.
-
-## Reading
-
-```bash
-cbx status               # what has changed in this folder since its last version
-cbx projects             # every project on the account
-cbx versions [project]   # what has been saved, newest first
-cbx tracks [project]     # the lines a project has, and any waiting on a decision
-```
-
-`status` is the one to reach for when somebody asks what is uncommitted, what
-changed, or whether anything needs saving. It reads the folder and changes
-nothing.
-
-## Saving
-
-```bash
-cbx submit -m "What changed, in a sentence"
-```
-
-Send only what changed; the version still names every file. Write the message
-yourself from the actual diff rather than asking for one — a message like
-"update" helps nobody reading the history later.
-
-**Ask before running this.** Saving is the one thing here that leaves a mark on
-somebody's account, and a version saved by mistake is a version they have to
-explain. Propose it, say what it would send, and let them agree.
-
-`cbx submit -n` shows exactly what would be sent without sending it. Use
-that freely; it is safe and it is the honest way to answer "what would this
-upload?".
-
-## Fetching
-
-```bash
-cbx get                  # bring this folder up to date
-cbx clone <project> [dir]  # fetch a project into a new folder
-```
-
-`get` protects local edits by default. `cbx get --replace` discards them
-to make an exact copy — only run it when the person has said so in those terms.
-
-## Lines of work
-
-A project can have more than one line, so two people can save without one
-landing on top of the other.
-
-```bash
-cbx track                 # which line this folder saves to
-cbx track spike --new     # start a line and switch to it
-cbx track main            # switch back
-cbx submit --track spike -m "…"
-```
-
-Switching says where the next save goes and nothing else — no files move.
-Run `cbx get` afterwards to bring that line's files in.
-
-## Versions, and going back
-
-Every save is a commit. A commit becomes a *version* — the thing the public
-side of a project offers, and the thing a collaborator pulls — only when
-somebody promotes it.
-
-```bash
-cbx promote                    # pick from the last ten and name one
-cbx mark 41 --pin              # pin, hide, rename or label one save
-cbx labels add shipped green   # the labels a project can wear
-cbx undo                       # put the project back on the save before this one
-```
-
-`undo` moves where the project stands. Nothing is deleted and nothing is
-renumbered — the saves passed over stay in the history, and the next save
-carries on from wherever it now stands. It is the answer to "I pushed the
-wrong thing"; hiding a version stops strangers reading it but leaves the
-project standing on it, so the next person to pull still lands on the mistake.
-
-**Ask before `undo`, `promote` and `take-down`.** They change what other
-people see. `cbx versions` first, so the person can say which save they mean.
-
-## When two saves collide
-
-If somebody saved while this folder was behind, the second save becomes a merge
-waiting on a decision rather than overwriting anything.
-
-```bash
-cbx merges                # this folder's saves waiting on a decision
-cbx merge <ref>           # look at one, and decide
-```
-
-Read the conflict out to the person and let them choose. Do not pick a side for
-them: the whole reason it stopped is that the service could not tell which copy
-was wanted.
-
-## What is worth leaving out
-
-```bash
-cbx ignore --suggest          # dependency directories, build output, virtual environments
-cbx ignore --suggest --apply  # add the confident ones to .gitignore
-```
-
-Rules live in the project's own `.gitignore`, so CodeRook, git and the website
-all read one file.
-
-## Bundles
-
-```bash
-cbx bundle . project.cbx   # the whole project, every version, as one file
-cbx inspect project.cbx    # what is inside, without unpacking
-cbx unbundle project.cbx ./restored
-```
-
-## Things not to do
-
-- Do not run `cbx delete` unless the person has asked for that project to
-  be deleted, by name, in this conversation.
-- Do not run `cbx sign-out`. It costs them a token they have to fetch
-  again and gains nothing.
-- Do not guess a project name. `cbx projects` lists them; a folder that is
-  already linked needs no name at all.
-- Do not run `cbx take-down`. It destroys the files in a version and they do
-  not come back. Say it exists and let its owner run it.
-
-## If something refuses
-
-The commands explain themselves — pass the message on rather than rewording it.
-A refusal that says a token was not accepted means signing in; one that says a
-project does not allow machines means its owner turned that off deliberately,
-and the answer is to say so, not to find another route in.
+---
+name: coderook
+description: Save, browse and restore versions of a project on CodeRook — a version host where every version is a complete snapshot and there is no git to learn. Use when asked to save or submit work to CodeRook, check what has changed, look at a project's versions or files, fetch a project, start or switch a line of work, or resolve a save that landed at the same time as somebody else's.
+allowed-tools: Bash Read
+---
+
+# CodeRook
+
+CodeRook stores whole snapshots of a folder. A version names every file the
+project had at that moment, so restoring one never depends on the versions
+around it, and there is no staging area, no branches to rebase and no history
+to rewrite.
+
+Everything here is the `coderook` command line. Run it with Bash.
+
+## Before anything else
+
+`cbx whoami` says who this machine is signed in as. If it refuses, the
+person needs to run `cbx sign-in` themselves — it takes a personal access
+token, so do not attempt it on their behalf.
+
+If the command is not found at all, this machine has the skill but not the
+command line. Either install it once with
+`npm install --global @coderook/cli`, or put `npx -y @coderook/cli` where
+`coderook` appears below — the commands are identical, npx is just slower
+to start.
+
+## Reading
+
+```bash
+cbx status               # what has changed in this folder since its last version
+cbx projects             # every project on the account
+cbx versions [project]   # what has been saved, newest first
+cbx tracks [project]     # the lines a project has, and any waiting on a decision
+```
+
+`status` is the one to reach for when somebody asks what is uncommitted, what
+changed, or whether anything needs saving. It reads the folder and changes
+nothing.
+
+## Saving
+
+```bash
+cbx submit -m "What changed, in a sentence"
+```
+
+Send only what changed; the version still names every file. Write the message
+yourself from the actual diff rather than asking for one — a message like
+"update" helps nobody reading the history later.
+
+**Ask before running this.** Saving is the one thing here that leaves a mark on
+somebody's account, and a version saved by mistake is a version they have to
+explain. Propose it, say what it would send, and let them agree.
+
+`cbx submit -n` shows exactly what would be sent without sending it. Use
+that freely; it is safe and it is the honest way to answer "what would this
+upload?".
+
+## Fetching
+
+```bash
+cbx get                  # bring this folder up to date
+cbx clone <project> [dir]  # fetch a project into a new folder
+```
+
+`get` protects local edits by default. `cbx get --replace` discards them
+to make an exact copy — only run it when the person has said so in those terms.
+
+## Lines of work
+
+A project can have more than one line, so two people can save without one
+landing on top of the other.
+
+```bash
+cbx track                 # which line this folder saves to
+cbx track spike --new     # start a line and switch to it
+cbx track main            # switch back
+cbx submit --track spike -m "…"
+```
+
+Switching says where the next save goes and nothing else — no files move.
+Run `cbx get` afterwards to bring that line's files in.
+
+## Versions, and going back
+
+Every save is a commit. A commit becomes a *version* — the thing the public
+side of a project offers, and the thing a collaborator pulls — only when
+somebody promotes it.
+
+```bash
+cbx promote                    # pick from the last ten and name one
+cbx mark 41 --pin              # pin, hide, rename or label one save
+cbx labels add shipped green   # the labels a project can wear
+cbx undo                       # put the project back on the save before this one
+```
+
+`undo` moves where the project stands. Nothing is deleted and nothing is
+renumbered — the saves passed over stay in the history, and the next save
+carries on from wherever it now stands. It is the answer to "I pushed the
+wrong thing"; hiding a version stops strangers reading it but leaves the
+project standing on it, so the next person to pull still lands on the mistake.
+
+**Ask before `undo`, `promote` and `take-down`.** They change what other
+people see. `cbx versions` first, so the person can say which save they mean.
+
+## When two saves collide
+
+If somebody saved while this folder was behind, the second save becomes a merge
+waiting on a decision rather than overwriting anything.
+
+```bash
+cbx merges                # this folder's saves waiting on a decision
+cbx merge <ref>           # look at one, and decide
+```
+
+Read the conflict out to the person and let them choose. Do not pick a side for
+them: the whole reason it stopped is that the service could not tell which copy
+was wanted.
+
+## What is worth leaving out
+
+```bash
+cbx ignore --suggest          # dependency directories, build output, virtual environments
+cbx ignore --suggest --apply  # add the confident ones to .gitignore
+```
+
+Rules live in the project's own `.gitignore`, so CodeRook, git and the website
+all read one file.
+
+## Bundles
+
+```bash
+cbx bundle . project.cbx   # the whole project, every version, as one file
+cbx inspect project.cbx    # what is inside, without unpacking
+cbx unbundle project.cbx ./restored
+```
+
+## Reading a public project without signing in
+
+Public projects can be read by anything, with no token, from
+`https://api.coderook.com/v1/public`. There is no need to read the command
+line's source to find these — this is the whole of it:
+
+```text
+GET /projects?q=                                  public projects, newest first
+GET /projects/{owner}/{slug}                      one project
+GET /projects/{owner}/{slug}/versions             the versions it offers
+GET /projects/{owner}/{slug}/releases/latest      newest release and its files
+GET /projects/{owner}/{slug}/updates/latest.yml   electron-updater feed
+GET /projects/{owner}/{slug}/versions/{v}/files         every file, with digests
+GET /projects/{owner}/{slug}/versions/{v}/file?path=    one file
+GET /projects/{owner}/{slug}/versions/{v}/archive       the version as a zip
+GET /projects/{owner}/{slug}/versions/{v}/attachments   files attached to it
+GET /projects/{owner}/{slug}/versions/{v}/attachments/{id}   download one
+```
+
+`{v}` is a version id or `latest`. A private project answers 404, exactly as
+if it did not exist.
+
+### An app that updates itself from CodeRook
+
+Release a version named like a version number and attach the installer:
+
+```bash
+cbx release 1.4.0
+cbx attach ./dist/MyApp-Setup-1.4.0.exe
+```
+
+An Electron app then needs nothing custom — electron-builder's generic
+provider pointed at the feed:
+
+```json
+"publish": [{ "provider": "generic",
+  "url": "https://api.coderook.com/v1/public/projects/OWNER/SLUG/updates" }]
+```
+
+The feed serves `latest.yml`, `latest-mac.yml` and `latest-linux.yml` with
+each file's size and SHA-512, and redirects file names to their downloads.
+Anything else can read `releases/latest` as JSON: version, notes, and every
+file with its size, SHA-256 and `url`. Updaters have no account, so the
+project they read must be public; keep private code in a separate project and
+ship releases from a public one.
+
+## Things not to do
+
+- Do not run `cbx delete` unless the person has asked for that project to
+  be deleted, by name, in this conversation.
+- Do not run `cbx sign-out`. It costs them a token they have to fetch
+  again and gains nothing.
+- Do not guess a project name. `cbx projects` lists them; a folder that is
+  already linked needs no name at all.
+- Do not run `cbx take-down`. It destroys the files in a version and they do
+  not come back. Say it exists and let its owner run it.
+
+## If something refuses
+
+The commands explain themselves — pass the message on rather than rewording it.
+A refusal that says a token was not accepted means signing in; one that says a
+project does not allow machines means its owner turned that off deliberately,
+and the answer is to say so, not to find another route in.