@coderook/cli 0.23.0 → 0.25.0

package/dist/cli/src/transfer_command.js

@@ -0,0 +1,331 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commandTransfer = commandTransfer;
+/**
+ * Moving a whole repository off a git host and onto CodeRook.
+ *
+ * `cbx import` takes a snapshot: the files as they are now, one version, no
+ * history. That is the right answer for "get this onto CodeRook quickly" and
+ * the wrong one for "move off GitHub", where the history, the branches, the
+ * tags and the issues are most of what somebody is worried about losing.
+ *
+ * ## It uses the public route on purpose
+ *
+ * The history goes across by running `git push` against the CodeRook remote —
+ * the same command anybody else would type, through the same helper. Nothing
+ * here reaches past it into a private path.
+ *
+ * That is deliberate, because the claim being made is interoperability. A
+ * transfer that worked through a back door would prove only that a back door
+ * exists. This one works because `git push coderook --all` works; if that ever
+ * breaks, this breaks with it, loudly, rather than quietly diverging from what
+ * users are told to do.
+ *
+ * ## What crosses, and what cannot
+ *
+ * Commits, branches, tags and the project's own description come across.
+ * Issues come across when a read token is supplied. Pull requests, reviews,
+ * CI configuration, stars and collaborator lists do not — some because
+ * CodeRook has no such object, and one because it would be wrong: adding
+ * somebody to a project is an invitation they have to accept, not a field to
+ * copy. The report at the end says which is which rather than leaving the
+ * absence to be discovered.
+ *
+ * ## Tokens
+ *
+ * Read from the environment, never from a flag and never stored. A read-only
+ * token is enough, and no OAuth flow is offered: holding somebody's forge
+ * credentials to run a one-off migration sits badly beside a front page that
+ * promises their work is not handed to anybody.
+ */
+const node_child_process_1 = require("node:child_process");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_process_1 = __importDefault(require("node:process"));
+const api_js_1 = require("./api.js");
+const forge_url_js_1 = require("./forge_url.js");
+const dim = (value) => `${value}`;
+const bold = (value) => `${value}`;
+const red = (value) => `${value}`;
+const green = (value) => `${value}`;
+const accent = (value) => `${value}`;
+/** A read token from the environment, or nothing. Never a flag. */
+function forgeToken(forge) {
+    for (const name of forge.tokenNames) {
+        const value = node_process_1.default.env[name]?.trim();
+        if (value)
+            return value;
+    }
+    return null;
+}
+async function readJson(url, token, forge) {
+    const headers = {
+        accept: "application/json",
+        "user-agent": "cbx-transfer",
+    };
+    if (token) {
+        headers.authorization =
+            forge.kind === "gitlab" ? `Bearer ${token}` : `token ${token}`;
+    }
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+        throw new Error(`${response.status} from ${new URL(url).pathname}`);
+    }
+    return response.json();
+}
+/** What the forge says about the repository itself. */
+async function describeSource(forge, token) {
+    const encoded = encodeURIComponent(`${forge.owner}/${forge.repo}`);
+    const url = forge.kind === "github"
+        ? `https://api.${forge.host}/repos/${forge.owner}/${forge.repo}`
+        : forge.kind === "gitlab"
+            ? `https://${forge.host}/api/v4/projects/${encoded}`
+            : `https://${forge.host}/api/v1/repos/${forge.owner}/${forge.repo}`;
+    try {
+        const body = (await readJson(url, token, forge));
+        const isPrivate = body.private === true || body.visibility === "private" || body.internal === true;
+        return {
+            description: String(body.description ?? "").slice(0, 1000),
+            visibility: isPrivate ? "private" : "public",
+            defaultBranch: body.default_branch ?? null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Open issues on the source, oldest first so numbering reads sensibly. */
+async function readIssues(forge, token) {
+    const encoded = encodeURIComponent(`${forge.owner}/${forge.repo}`);
+    const url = forge.kind === "github"
+        ? `https://api.${forge.host}/repos/${forge.owner}/${forge.repo}/issues?state=open&per_page=100`
+        : forge.kind === "gitlab"
+            ? `https://${forge.host}/api/v4/projects/${encoded}/issues?state=opened&per_page=100`
+            : `https://${forge.host}/api/v1/repos/${forge.owner}/${forge.repo}/issues?state=open&limit=100`;
+    const body = (await readJson(url, token, forge));
+    return body
+        /*
+          GitHub returns pull requests through the issues endpoint. They are not
+          issues, and CodeRook has nothing that a pull request becomes, so copying
+          them across as issues would be inventing content rather than moving it.
+        */
+        .filter((one) => !one.pull_request)
+        .map((one) => ({
+        title: String(one.title ?? "").slice(0, 200),
+        body: String(one.body ?? one.description ?? "").slice(0, 20_000),
+        number: Number(one.number ?? one.iid ?? 0),
+        closed: false,
+    }))
+        .filter((one) => one.title)
+        .reverse();
+}
+function run(command, args, cwd) {
+    const result = (0, node_child_process_1.spawnSync)(command, args, {
+        cwd,
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024 * 64,
+    });
+    return {
+        ok: result.status === 0,
+        out: `${result.stdout ?? ""}${result.stderr ?? ""}`,
+    };
+}
+async function commandTransfer(parsed) {
+    const address = parsed.positional[0];
+    if (!address) {
+        console.error(red("Which repository? Try: cbx transfer https://github.com/owner/project"));
+        return 1;
+    }
+    let forge;
+    try {
+        forge = (0, forge_url_js_1.readForgeUrl)(address);
+    }
+    catch (error) {
+        console.error(red(error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+    if (!run("git", ["--version"]).ok) {
+        console.error(red("Transferring needs git on this machine."));
+        return 1;
+    }
+    /*
+      The push goes through the remote helper, which git finds on PATH by name.
+      Checking now turns a confusing failure halfway through a clone into one
+      sentence before anything is downloaded.
+    */
+    if (!run("git", ["remote-coderook", "--probe"]).ok) {
+        const help = run("git", ["help", "-a"]);
+        if (!/remote-coderook/.test(help.out)) {
+            console.error(red("git cannot find `git-remote-coderook` on this machine."));
+            console.error("It ships with this tool, so this usually means cbx was run from a\n" +
+                "checkout rather than installed. Install it globally and try again:\n" +
+                `  ${accent("npm install --global @coderook/cli")}`);
+            return 1;
+        }
+    }
+    const wanted = (typeof parsed.flags.get("name") === "string"
+        ? String(parsed.flags.get("name"))
+        : forge.repo).toLowerCase();
+    const existing = await (0, api_js_1.findProject)(wanted);
+    if (existing) {
+        console.error(red(`You already have a project called ${existing.slug}.`));
+        console.error(`Transfer creates a project; it does not merge into one. Choose another\n` +
+            `name with ${accent("--name")}, or delete that project first.`);
+        return 1;
+    }
+    const token = forgeToken(forge);
+    console.log(`${bold("Transferring")} ${forge.owner}/${forge.repo} ${dim(`from ${forge.label}`)}`);
+    console.log(dim(token
+        ? `  Using the read token in ${forge.tokenNames.find((name) => node_process_1.default.env[name]?.trim())}.`
+        : `  No token set. Public repositories work; set ${forge.tokenNames[0]} for a private one or for issues.`));
+    const scratch = await (0, promises_1.mkdtemp)(node_path_1.default.join(node_os_1.default.tmpdir(), "cbx-transfer-"));
+    const checkout = node_path_1.default.join(scratch, forge.repo);
+    const report = [];
+    try {
+        /*
+          A full clone, not the shallow one `import` uses. The whole point here is
+          the history, and `--depth 1` would silently deliver a single commit under
+          a command whose name promises everything.
+        */
+        console.log(`\n${dim("Fetching the repository with its full history…")}`);
+        const cloned = run("git", ["clone", "--no-single-branch", forge.clone, checkout]);
+        if (!cloned.ok) {
+            console.error(red(`\nCould not clone ${forge.clone}`));
+            console.error(cloned.out.trim().split("\n").slice(-4).join("\n"));
+            if (!token) {
+                console.error(dim(`\nIf it is private, set ${forge.tokenNames[0]} and try again.`));
+            }
+            return 1;
+        }
+        /*
+          Every branch, not only the one checked out. A fresh clone has remote
+          tracking refs for the rest, and nothing local pointing at them, so
+          `--all` would push exactly one branch.
+        */
+        const remoteBranches = run("git", [
+            "for-each-ref", "--format=%(refname:short)", "refs/remotes/origin",
+        ], checkout).out
+            .split("\n").map((one) => one.trim()).filter(Boolean)
+            /*
+              The remote's HEAD symref comes back as plain `origin`, not
+              `origin/HEAD`, so filtering on the latter leaves a phantom entry that
+              inflates the branch count and sends git looking for `origin/origin`.
+            */
+            .filter((one) => one.startsWith("origin/"))
+            .map((one) => one.slice("origin/".length))
+            .filter((one) => one && one !== "HEAD");
+        for (const branch of remoteBranches) {
+            run("git", ["branch", "--force", branch, `origin/${branch}`], checkout);
+        }
+        const commits = Number(run("git", ["rev-list", "--all", "--count"], checkout).out.trim() || "0");
+        const tags = run("git", ["tag", "-l"], checkout).out.split("\n").filter(Boolean);
+        console.log(`  ${commits} commit${commits === 1 ? "" : "s"} · ` +
+            `${remoteBranches.length} branch${remoteBranches.length === 1 ? "" : "es"} · ` +
+            `${tags.length} tag${tags.length === 1 ? "" : "s"}`);
+        if (commits > 200) {
+            console.log(dim(`  Each commit becomes a version, so this will take a while —\n` +
+                `  roughly ${Math.round((commits * 11) / 60)} minutes. It resumes if interrupted.`));
+        }
+        run("git", ["remote", "add", "coderook", `coderook://${wanted}`], checkout);
+        console.log(`\n${dim("Publishing the history…")}`);
+        const pushed = run("git", ["push", "coderook", "--all"], checkout);
+        node_process_1.default.stderr.write(pushed.out);
+        if (!pushed.ok) {
+            console.error(red("\nThe history did not transfer completely."));
+            return 1;
+        }
+        report.push(`${commits} commits across ${remoteBranches.length} branch(es)`);
+        if (tags.length) {
+            const pushedTags = run("git", ["push", "coderook", "--tags"], checkout);
+            node_process_1.default.stderr.write(pushedTags.out);
+            report.push(pushedTags.ok
+                ? `${tags.length} tag(s) as releases`
+                : `tags were refused — see above`);
+        }
+        const project = await (0, api_js_1.findProject)(wanted);
+        if (!project) {
+            console.error(red("\nThe project was not created. Nothing else was changed."));
+            return 1;
+        }
+        // What the repository says about itself.
+        const facts = await describeSource(forge, token);
+        if (facts) {
+            const asked = parsed.flags.get("visibility");
+            /*
+              Private unless asked otherwise, even when the source is public.
+              Mirroring visibility is the faithful thing and publishing somebody's
+              code by side effect is the unrecoverable thing, so the safe reading
+              wins and the report says what was chosen.
+            */
+            const visibility = asked === "same"
+                ? facts.visibility
+                : asked === "public"
+                    ? "public"
+                    : "private";
+            await (0, api_js_1.updateProject)(project.id, {
+                ...(facts.description ? { description: facts.description } : {}),
+                visibility,
+            });
+            report.push(`description and visibility (${visibility}` +
+                `${visibility !== facts.visibility ? `, source was ${facts.visibility}` : ""})`);
+            /*
+              Said rather than left to be noticed. Creating a project always makes a
+              `main` line, so a repository whose default is anything else arrives
+              with an empty one beside its real branches — and `cbx tracks` marks it
+              as the current line, which reads as though the transfer lost the work.
+            */
+            if (facts.defaultBranch && facts.defaultBranch !== "main") {
+                report.push(`default line is ${facts.defaultBranch}; the empty "main" beside it ` +
+                    `was made when the project was created`);
+            }
+        }
+        else {
+            report.push("description could not be read from the source");
+        }
+        // Issues, only when asked and only with a token.
+        if (parsed.flags.has("issues")) {
+            if (!token) {
+                report.push(`issues skipped — set ${forge.tokenNames[0]} and run with --issues again`);
+            }
+            else {
+                try {
+                    const issues = await readIssues(forge, token);
+                    let made = 0;
+                    for (const issue of issues) {
+                        await (0, api_js_1.createIssue)(project.id, {
+                            title: issue.title,
+                            body: `${issue.body}\n\n` +
+                                `— transferred from ${forge.label} ${forge.owner}/${forge.repo}#${issue.number}`,
+                        });
+                        made += 1;
+                    }
+                    report.push(`${made} open issue(s)`);
+                }
+                catch (error) {
+                    report.push(`issues failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+        console.log(`\n${green("Transferred")} ${bold(project.slug)}`);
+        for (const line of report)
+            console.log(`  ${green("·")} ${line}`);
+        console.log(`\n${dim("Not carried across:")}`);
+        console.log(dim("  · pull requests and reviews — CodeRook has no equivalent object"));
+        console.log(dim("  · CI configuration — runs are started deliberately, not by a push"));
+        console.log(dim("  · collaborators — access is an invitation to accept, not a field to copy"));
+        console.log(dim("  · stars, forks and watchers"));
+        if (!parsed.flags.has("issues")) {
+            console.log(dim("  · issues — pass --issues to bring the open ones"));
+        }
+        console.log(`\nFetch it anywhere with ${accent(`cbx clone ${project.slug}`)}` +
+            `${dim(", or ")}${accent(`git clone coderook://${project.slug}`)}${dim(".")}`);
+        return 0;
+    }
+    finally {
+        await (0, promises_1.rm)(scratch, { recursive: true, force: true });
+    }
+}

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

@@ -77,8 +77,18 @@ class Tracks {
      * accept, so this passes the name through rather than pre-judging it —
      * a rule enforced in two places is a rule that will disagree with itself.
      */
-    async create(repositoryId, name) {
-        const body = await this.call(`/v1/repositories/${repositoryId}/tracks`, { method: "POST", body: JSON.stringify({ name }) });
+    async create(repositoryId, name, 
+    /*
+      Where the line starts, when the caller knows better than "wherever the
+      project is now". Somebody clicking New line means from here; a git branch
+      means from the version matching the commit it forked at, which is
+      usually not the head. Omitted keeps the original behaviour exactly.
+    */
+    fromVersionId) {
+        const body = await this.call(`/v1/repositories/${repositoryId}/tracks`, {
+            method: "POST",
+            body: JSON.stringify(fromVersionId ? { name, fromVersionId } : { name }),
+        });
         return body.track;
     }
     /** Merges that have not been applied or abandoned. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coderook/cli",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "CodeRook from the command line, on any operating system",
   "license": "SEE LICENSE IN LICENSE.txt",
   "homepage": "https://coderook.com",
@@ -17,7 +17,9 @@
     "node": ">=20.11.0"
   },
   "bin": {
-    "coderook": "dist/cli/src/cli.js"
+    "cbx": "dist/cli/src/cli.js",
+    "coderook": "dist/cli/src/cli.js",
+    "git-remote-coderook": "dist/cli/src/git_remote_bin.js"
   },
   "files": [
     ".claude-plugin",
@@ -34,7 +36,7 @@
     "test:matrix": "node test/state-matrix.mjs",
     "test:attempt": "node test/attempt-identity.mjs",
     "test:get": "node test/get-safety.mjs",
-    "test:live": "node test/e2e.mjs --allow-production && node test/state-matrix.mjs --allow-production && node test/get-safety.mjs --allow-production && node test/get-protects-edits.mjs --allow-production && node test/upgrade-migration.mjs --allow-production && node test/fault-get.mjs --allow-production && node test/version-floor.mjs --allow-production && node test/fault-submit.mjs --allow-production && node test/race-attempts.mjs --allow-production && node test/attempt-identity.mjs --allow-production",
+    "test:live": "node test/e2e.mjs --allow-production && node test/state-matrix.mjs --allow-production && node test/get-safety.mjs --allow-production && node test/get-track.mjs --allow-production && node test/get-protects-edits.mjs --allow-production && node test/upgrade-migration.mjs --allow-production && node test/fault-get.mjs --allow-production && node test/version-floor.mjs --allow-production && node test/fault-submit.mjs --allow-production && node test/race-attempts.mjs --allow-production && node test/attempt-identity.mjs --allow-production",
     "test:getedits": "node test/get-protects-edits.mjs",
     "test:upgrade": "node test/upgrade-migration.mjs",
     "test:faultget": "node test/fault-get.mjs",
@@ -42,7 +44,8 @@
     "test:faultsubmit": "node test/fault-submit.mjs",
     "test:race": "node test/race-attempts.mjs",
     "test:runner": "node test/runner-live.mjs",
-    "sync:plugin": "node scripts/sync-plugin-version.mjs"
+    "sync:plugin": "node scripts/sync-plugin-version.mjs",
+    "test:track": "node test/get-track.mjs"
   },
   "devDependencies": {
     "@types/node": "24.10.1",

package/skills/coderook/SKILL.md

@@ -1,130 +1,130 @@
----
-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
-
-`coderook whoami` says who this machine is signed in as. If it refuses, the
-person needs to run `coderook 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
-coderook status               # what has changed in this folder since its last version
-coderook projects             # every project on the account
-coderook versions [project]   # what has been saved, newest first
-coderook 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
-coderook 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.
-
-`coderook 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
-coderook get                  # bring this folder up to date
-coderook clone <project> [dir]  # fetch a project into a new folder
-```
-
-`get` protects local edits by default. `coderook 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
-coderook track                 # which line this folder saves to
-coderook track spike --new     # start a line and switch to it
-coderook track main            # switch back
-coderook submit --track spike -m "…"
-```
-
-Switching says where the next save goes and nothing else — no files move.
-Run `coderook get` afterwards to bring that line's files in.
-
-## 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
-coderook merges                # this folder's saves waiting on a decision
-coderook 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
-coderook ignore --suggest          # dependency directories, build output, virtual environments
-coderook 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
-coderook bundle . project.cbx   # the whole project, every version, as one file
-coderook inspect project.cbx    # what is inside, without unpacking
-coderook unbundle project.cbx ./restored
-```
-
-## Things not to do
-
-- Do not run `coderook delete` unless the person has asked for that project to
-  be deleted, by name, in this conversation.
-- Do not run `coderook sign-out`. It costs them a token they have to fetch
-  again and gains nothing.
-- Do not guess a project name. `coderook projects` lists them; a folder that is
-  already linked needs no name at all.
-
-## 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.
+
+## 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.
+
+## 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.