@coderook/cli 0.31.8 → 0.31.10

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.8",
+  "version": "0.31.10",
   "author": {
     "name": "ACCA Gaming Productions",
     "url": "https://coderook.com"

package/README.md

@@ -1,389 +1,455 @@
-# cbx
-
-The command is `cbx`, and the split it names is the same one git and GitHub
-have. **CBX is the engine** — content-defined chunking, whole-snapshot
-versions, the `.cbx` bundle format. **CodeRook is the host** it talks to. You
-run `cbx`; you sign in to CodeRook.
-
-That is why the names do not match everywhere, and the mismatch is on purpose:
-
-| | |
-| --- | --- |
-| `cbx …` | the tool — what you type |
-| `coderook.com`, `@coderook/cli` | the service, and the package it ships in |
-| `coderook://project` | a remote URL, which names the host it points at |
-| `CODEROOK_TOKEN`, `%APPDATA%\CodeRook` | credentials for a CodeRook account |
-
-It uses the same engines as the desktop application — the same scanner, the
-same `.gitignore` rules, the same upload, download and `.cbx` bundling — so a
-project moved by one is understood by the other.
-
-## Install
-
-Requires Node 20.11 or later, and nothing else.
-
-```
-npm install --global @coderook/cli
-```
-
-That installs `cbx`. It also installs `coderook` as an alias for it, so
-anything written against the old name keeps working; the two are the same
-program and either can be used.
-
-Or from this repository:
-
-```
-cd cli
-npm install
-npm run build
-npm link
-```
-
-## Sign in
-
-Create a personal access token in **Settings** on coderook.com, then:
-
-```
-cbx sign-in
-```
-
-The token is written to a file only your account can read:
-
-| Platform | Location |
-| --- | --- |
-| Windows | `%APPDATA%\CodeRook` |
-| macOS | `~/Library/Application Support/CodeRook` |
-| Linux | `$XDG_CONFIG_HOME/coderook`, or `~/.config/coderook` |
-
-For automation, set `CODEROOK_TOKEN` instead and nothing is written to disk.
-`CODEROOK_API_URL` points the tool at a different service.
-
-## Everyday use
-
-```
-cbx status                    what is here that is not saved yet
-cbx submit -m "Fixed the parser"
-cbx get                       fetch the latest version over this folder
-cbx clone my-project          fetch a project into a new folder
-```
-
-`status` and `submit` act on the current directory unless you name another.
-The first time either runs in a folder, it looks for a project on your account
-whose name matches and links the two, so a folder you already uploaded from
-the desktop is recognised rather than treated as new.
-
-`submit` sends only what changed. Files the service already holds are not
-uploaded again, and the version it records still names every file in the
-project — a version is a snapshot, not a difference.
-
-## Lines of work
-
-A project can have more than one line, so two people can save without one
-landing on top of the other.
-
-```
-cbx tracks                    the lines this project has
-cbx track                     the 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 "Try the other encoder"
-```
-
-Switching says where the next save goes and nothing else. No files move and
-nothing is fetched, so it is instant and safe to change your mind — run
-`cbx get` afterwards to bring that line's files into the folder.
-
-The line is remembered per folder, not per account, so two checkouts of one
-project can sit on different lines. A folder that has never been switched
-saves to `main`, which is what every folder meant before lines existed.
-
-A name that does not exist is refused rather than created. A typo in a branch
-name is an ordinary thing to do, and a line called `mian` puts work somewhere
-nobody will look for it — `--new` is how you say you meant it.
-
-If two saves land on the same line anyway, the second becomes a merge waiting
-on a decision. `cbx merges` lists them and `cbx merge <ref>` walks
-through it; `cbx tracks` shows them beside the ordinary lines, because
-somebody looking for where they can save needs to see the one they cannot.
-
-## Ignore rules
-
-```
-cbx ignore                     show the rules in force
-cbx ignore --init              write a starter .gitignore
-cbx ignore --suggest           what is here that probably should not be sent
-cbx ignore --suggest --apply   add the confident ones
-```
-
-`cbx rules` is the same command under another name, so anything already
-written against it keeps working.
-
-`--suggest` looks at what the folder would actually send and names the
-dependency directories, virtual environments and build output in it, with how
-much each is costing you. Lines marked `+` are safe to assume and are the ones
-`--apply` writes; anything that might be the work itself is marked `?` and left
-for you, because the cost of guessing wrong is a project that is not backed up.
-
-Rules live in the project's own `.gitignore`, so CodeRook, git, the website
-and the desktop application all read one file. A `!` line puts something back.
-Personal exclusions that should not reach a collaborator belong in
-`.git/info/exclude`.
-
-## Moving a repository here
-
-`cbx import` takes a snapshot — the files as they are now, one version, no
-history. To move off a host entirely, with the history intact:
-
-```
-cbx transfer https://github.com/owner/project
-```
-
-GitHub, GitLab, Codeberg and any self-hosted Gitea or Forgejo. Every commit
-becomes a version and every branch a line, so it takes a while on a long
-history — the commit count and an estimate are printed before it starts.
-
-**It goes through the public route on purpose.** The history is published by
-running `git push` against the CodeRook remote, exactly as you would by hand.
-A transfer that used a private path would prove only that a private path
-exists.
-
-| | |
-| --- | --- |
-| Comes across | commits, every branch, tags as releases, the description |
-| With `--issues` and a read token | the open issues |
-| Does not come across | pull requests and reviews, CI configuration, collaborators, stars |
-
-The project is created **private** whatever the source was — publishing
-somebody's code as a side effect of moving it is not recoverable. Pass
-`--visibility same` to mirror the source, or `--public`.
-
-A private repository needs a read token in the environment — `GITHUB_TOKEN`,
-`GITLAB_TOKEN` or `FORGE_TOKEN`. It is never taken as a flag, never stored,
-and there is no OAuth flow: holding your forge credentials to run a one-off
-migration sits badly beside a promise that your work is not handed to anybody.
-
-The report at the end lists what arrived and what did not, rather than leaving
-the absence to be discovered later.
-
-## Using git instead
-
-Installing the CLI also installs `git-remote-coderook`, so git talks to
-CodeRook directly — both ways:
-
-```
-git clone coderook://my-project
-git push coderook main
-git fetch
-```
-
-It exists so that every editor's built-in git panel works with CodeRook
-without a plugin. If you are not already living in git, `cbx submit` is
-the simpler tool and this is not an upgrade on it.
-
-**Pushing.** Each commit becomes a version, oldest first, with its message
-kept. Later pushes send only what is new, so the usual case — a few commits —
-is quick; a first push of a long history is not, and the helper says how many
-commits it is about to publish before it starts. Branches become lines, and a
-branch pushed for the first time starts from the commit it forked at rather
-than from wherever the project happens to be.
-
-**Cloning and fetching.** Every version becomes a commit, keeping its message,
-its date and who published it. This works on any project, including one that
-has never been near git — a project built entirely with `cbx submit`
-clones into a normal git history. A fetch only downloads versions this clone
-does not already have.
-
-**What it does not do:**
-
-| | |
-| --- | --- |
-| Tag kind | A lightweight tag comes back annotated. CodeRook records a name, not which sort of tag made it. |
-| Force pushes, branch deletion | Refused — versions are immutable, so there is nothing to rewind to. |
-| Submodules | Skipped on push, and it says which paths. |
-| The executable bit | Everything arrives as a normal file. A script cloned back needs `chmod +x`. |
-
-**On round trips.** Push then clone gives you back the same *files*, not the
-same *commit ids*. A commit id covers its author, committer and timestamps,
-and CodeRook records who published a version rather than the original stamps —
-so the history you get back is a faithful copy of the contents and an honest
-approximation of the commits. Two people cloning the same project do get
-identical ids as each other.
-
-Merges are asymmetric for the same reason. A publish states one base version,
-so pushing a git merge records one parent and the fork is lost — the merged
-tree is exact, the shape is not. Reading back is richer: a version that really
-has two parents is rebuilt as a real git merge.
-
-Each version records the commit it came from, so a colleague pushing the same
-project does not republish history the project already holds. Pushing a git
-history into a project whose versions came from somewhere else is refused
-rather than interleaved.
-
-### The names are the same
-
-There is no translation table to learn, because there is nothing to translate.
-The commands carry git's names:
-
-```
-cbx push          cbx pull          cbx clone
-cbx log           cbx status        cbx branch
-cbx checkout      cbx merge         cbx tag
-```
-
-Each is the CodeRook command it always was, reachable by the name a git user
-would reach for: `push` is `submit`, `pull` is `get`, `log` is `versions`,
-`branch` is `tracks`, `checkout` is `track`, `tag` is `release`. The original
-names still work and mean the same thing.
-
-That is also what the git remote does. `git push` performs the operation
-`cbx push` performs — the same code decides what changed, the same code
-publishes it. The remote is a way to reach these commands from git, not a
-second implementation of them that happens to agree.
-
-**What does not appear on that list**, because git has no such idea and
-inventing one would be pretending: `projects`, `delete`, `people`, `watch`,
-`issues`, `actions`, `runs`, `logs`, `runner`, `tokens`, `licence`, `ai`. Use
-them by name; nothing about them changes when a version arrives through git.
-
-`git commit` has no CodeRook equivalent either, and should not: it is local to
-git, and a version is not made until something is published.
-
-### Tags and releases
-
-`git push --tags` publishes each tag as a release, because that is the same
-statement in the other vocabulary — the service puts it plainly: *"a release
-is a Version with a name on it, not a different kind of object."*
-
-```
-git tag -a v1.0 -m "First stable release"
-git push coderook v1.0
-```
-
-The tag names the version its commit already became; it does not publish
-anything, so push the branch first. An annotated tag's message becomes the
-release notes and a lightweight tag brings none — the commit's own message is
-deliberately *not* used, since nobody wrote it about the release.
-
-Cloning reverses it: every release comes back as a tag on the right commit.
-
-Assets are separate and unaffected. They attach to a version from a run's
-artifacts, so a release made by pushing a tag simply has none until something
-adds them — which is what a release without a build has always looked like.
-
-## Bundles
-
-```
-cbx bundle                    pack this project as <name>.cbx
-cbx unbundle backup.cbx       extract one
-cbx inspect backup.cbx        see what it holds  (--files to list them)
-```
-
-A `.cbx` is the CodeBox bundle format: content-defined chunks, Zstandard where
-it helps, raw where it does not, and a SHA-256 for every chunk and file.
-Extraction is verified and atomic — a damaged bundle fails rather than leaving
-a half-written tree.
-
-## Claude Code
-
-Run this **in a terminal**, not inside Claude Code:
-
-```bash
-cbx skill
-```
-
-That is the whole setup. It writes `~/.claude/skills/coderook/SKILL.md`, and
-from then on you ask for what you want in ordinary words:
-
-> save this to CodeRook
-
-> what have I changed?
-
-> what versions does this project have?
-
-Claude works out which commands to run. You can also call it by name with
-`/coderook`.
-
-**The skill is called `coderook`, not `cbx`.** `cbx` is the command line, run
-in a terminal; the skill is the file that teaches Claude how to use it. Typing
-`cbx skill` *into* Claude Code asks it for a skill by that name and it will
-tell you there is not one — which is correct, and is why the line above says
-where to run it.
-
-`cbx skill --project` writes it into `./.claude` instead of your home
-folder, so it travels with the repository and everybody who clones it has it
-too.
-
-Sign in once per machine first — `cbx sign-in` — or set `CODEROOK_TOKEN`
-in automation. The skill will not save anything without asking you first, and
-never deletes.
-
-## Installing it as a plugin instead
-
-If you would rather not install the command line first, CodeRook publishes a
-plugin marketplace of its own:
-
-```
-/plugin marketplace add https://coderook.com/marketplace.json
-/plugin install coderook@coderook
-```
-
-That fetches the same package from npm and brings the skill with it. The
-marketplace is a plain file on coderook.com rather than a git repository, so
-there is no repository to clone and no second account anywhere.
-
-One thing to know: a plugin install puts the package in Claude Code's plugin
-folder, not on your `PATH`. The skill copes with that on its own by falling
-back to `npx -y @coderook/cli`, but `npm install --global @coderook/cli` is
-faster if you plan to run commands yourself as well.
-
-## A structured connection instead
-
-The skill teaches Claude the command line, which needs no configuration. If you
-would rather it had structured tools, there is an MCP server as well. It works
-with Codex too, which is the reason it exists.
-
-Claude Code:
-
-```
-claude mcp add --scope user coderook -- npx -y @coderook/cli mcp
-```
-
-Codex, in `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.coderook]
-command = "npx"
-args = ["-y", "@coderook/cli", "mcp"]
-```
-
-To share it with everyone on a project, commit this beside the code:
-
-```json
-// .mcp.json
-{
-  "mcpServers": {
-    "coderook": {
-      "command": "npx",
-      "args": ["-y", "@coderook/cli", "mcp"]
-    }
-  }
-}
-```
-
-It offers five things, all of which read: your projects, a project's versions,
-the files in a version, one file's contents at a version, and what has changed
-in a local folder. It cannot save, delete, or sign in or out.
-
-## Checking things
-
-```
-cbx doctor
-```
-
-Reports the tool's version, where its configuration lives, whether the service
-is reachable, and who this machine is signed in as.
-
-## Exit codes
-
-`0` on success, `1` on failure. Every command prints why it failed on standard
-error, so a script can branch on the status and log the reason.
+# cbx
+
+The command line for [CodeRook](https://coderook.com), version control and
+project hosting for projects of any size. Every save is a complete,
+compressed snapshot of the folder; projects are private or public at your
+choice; and nothing stored on CodeRook is used to train AI. There is also a
+[desktop app](https://coderook.com/download) and the website, and all three do
+the same things. [How CodeRook works](https://coderook.com/docs).
+
+```
+npm install -g @coderook/cli
+cbx login
+```
+
+The command is `cbx`, and the split it names is the same one git and GitHub
+have. **CBX is the engine** — content-defined chunking, whole-snapshot
+versions, the `.cbx` bundle format. **CodeRook is the host** it talks to. You
+run `cbx`; you sign in to CodeRook.
+
+That is why the names do not match everywhere, and the mismatch is on purpose:
+
+| | |
+| --- | --- |
+| `cbx …` | the tool — what you type |
+| `coderook.com`, `@coderook/cli` | the service, and the package it ships in |
+| `coderook://project` | a remote URL, which names the host it points at |
+| `CODEROOK_TOKEN`, `%APPDATA%\CodeRook` | credentials for a CodeRook account |
+
+It uses the same engines as the desktop application — the same scanner, the
+same `.gitignore` rules, the same upload, download and `.cbx` bundling — so a
+project moved by one is understood by the other.
+
+## Install
+
+Requires Node 20.11 or later, and nothing else.
+
+```
+npm install --global @coderook/cli
+```
+
+That installs `cbx`. It also installs `coderook` as an alias for it, so
+anything written against the old name keeps working; the two are the same
+program and either can be used.
+
+Or from this repository:
+
+```
+cd cli
+npm install
+npm run build
+npm link
+```
+
+## Sign in
+
+Create a personal access token in **Settings** on coderook.com, then:
+
+```
+cbx sign-in
+```
+
+The token is written to a file only your account can read:
+
+| Platform | Location |
+| --- | --- |
+| Windows | `%APPDATA%\CodeRook` |
+| macOS | `~/Library/Application Support/CodeRook` |
+| Linux | `$XDG_CONFIG_HOME/coderook`, or `~/.config/coderook` |
+
+For automation, set `CODEROOK_TOKEN` instead and nothing is written to disk.
+`CODEROOK_API_URL` points the tool at a different service.
+
+## Everyday use
+
+```
+cbx status                    what is here that is not saved yet
+cbx submit -m "Fixed the parser"
+cbx get                       fetch the latest version over this folder
+cbx clone my-project          fetch a project into a new folder
+```
+
+`status` and `submit` act on the current directory unless you name another.
+The first time either runs in a folder, it looks for a project on your account
+whose name matches and links the two, so a folder you already uploaded from
+the desktop is recognised rather than treated as new.
+
+`submit` sends only what changed. Files the service already holds are not
+uploaded again, and the version it records still names every file in the
+project — a version is a snapshot, not a difference.
+
+## Lines of work
+
+A project can have more than one line, so two people can save without one
+landing on top of the other.
+
+```
+cbx tracks                    the lines this project has
+cbx track                     the 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 "Try the other encoder"
+```
+
+Switching says where the next save goes and nothing else. No files move and
+nothing is fetched, so it is instant and safe to change your mind — run
+`cbx get` afterwards to bring that line's files into the folder.
+
+The line is remembered per folder, not per account, so two checkouts of one
+project can sit on different lines. A folder that has never been switched
+saves to `main`, which is what every folder meant before lines existed.
+
+A name that does not exist is refused rather than created. A typo in a branch
+name is an ordinary thing to do, and a line called `mian` puts work somewhere
+nobody will look for it — `--new` is how you say you meant it.
+
+If two saves land on the same line anyway, the second becomes a merge waiting
+on a decision. `cbx merges` lists them and `cbx merge <ref>` walks
+through it; `cbx tracks` shows them beside the ordinary lines, because
+somebody looking for where they can save needs to see the one they cannot.
+
+## Proposals
+
+A line gets back to main by being proposed. The proposal is checked and
+reviewed before it lands, and it follows the line: saving onto it afterwards
+changes what is proposed rather than needing a second one.
+
+```
+cbx propose -m "Faster encoder"     offer this folder's line to main
+cbx proposals                       what is open (--all for the rest)
+cbx merge M-3                       look at one: reviews, checks, decisions
+cbx merge M-3 --ask sam,priya       ask people to review it
+cbx merge M-3 --apply               land it, once nothing is in the way
+```
+
+`--into` proposes into a line other than main, and `--from` proposes a line
+other than the one this folder is on. "Fixes #12" in the title or body closes
+issue 12 when it lands. The same proposals are on the website's Merges page
+and behind **propose** in the desktop application.
+
+A line can require approvals, and an approval from whoever proposed it does
+not count. Checks come from actions: `cbx actions --on-proposal Tests` runs
+Tests whenever a line is proposed or saved onto, and its result is a required
+check. `--on-save` runs an action on every save, and `--by-hand` only when
+somebody starts it.
+
+A **protected** line refuses saves made straight onto it — from `cbx submit`,
+the desktop application and `git push` alike — so the way in is a line of your
+own and a proposal. It also cannot be put back on an earlier save, and a merge
+cannot land on it over a conflict or a failing check.
+
+## Who can reach a project
+
+    cbx visibility                        # what it is now, and what each level means
+    cbx visibility public                 # list it on your profile
+    cbx visibility unlisted my-project    # link only: kept off your profile and out of search
+    cbx visibility private                # back to you and the people you invite
+
+Making a project public or unlisted asks first and says what becomes readable.
+In a script there is nobody to ask, so pass `--yes` (or `-y`); without it the
+command refuses rather than waiting. Going private never asks.
+
+A public project's page offers only its named versions that have not been
+hidden (see `cbx promote` and `cbx mark --hide`).
+
+## Ignore rules
+
+```
+cbx ignore                     show the rules in force
+cbx ignore --init              write a starter .gitignore
+cbx ignore --suggest           what is here that probably should not be sent
+cbx ignore --suggest --apply   add the confident ones
+```
+
+`cbx rules` is the same command under another name, so anything already
+written against it keeps working.
+
+`--suggest` looks at what the folder would actually send and names the
+dependency directories, virtual environments and build output in it, with how
+much each is costing you. Lines marked `+` are safe to assume and are the ones
+`--apply` writes; anything that might be the work itself is marked `?` and left
+for you, because the cost of guessing wrong is a project that is not backed up.
+
+Rules live in the project's own `.gitignore`, so CodeRook, git, the website
+and the desktop application all read one file. A `!` line puts something back.
+Personal exclusions that should not reach a collaborator belong in
+`.git/info/exclude`.
+
+In a git repository, a file git already tracks is sent even if a rule matches
+it — the same exception git makes, so a broad rule written after the fact does
+not quietly drop committed source. Git's own `.git` directory is never sent,
+and the service refuses a save with any path inside one.
+
+## Moving a repository here
+
+`cbx import` takes a snapshot — the files as they are now, one version, no
+history. To move off a host entirely, with the history intact:
+
+```
+cbx transfer https://github.com/owner/project
+```
+
+GitHub, GitLab, Codeberg and any self-hosted Gitea or Forgejo. Every commit
+becomes a version and every branch a line, so it takes a while on a long
+history — the commit count and an estimate are printed before it starts.
+
+**It goes through the public route on purpose.** The history is published by
+running `git push` against the CodeRook remote, exactly as you would by hand.
+A transfer that used a private path would prove only that a private path
+exists.
+
+| | |
+| --- | --- |
+| Comes across | commits, every branch, tags as releases, the description |
+| With `--issues` and a read token | the open issues |
+| Does not come across | pull requests and reviews, CI configuration, collaborators, stars |
+
+The project is created **private** whatever the source was — publishing
+somebody's code as a side effect of moving it is not recoverable. Pass
+`--visibility same` to mirror the source, or `--visibility public`.
+
+A private repository needs a read token in the environment — `GITHUB_TOKEN`,
+`GITLAB_TOKEN` or `FORGE_TOKEN`. It is never taken as a flag, never stored,
+and there is no OAuth flow: holding your forge credentials to run a one-off
+migration sits badly beside a promise that your work is not handed to anybody.
+
+The report at the end lists what arrived and what did not, rather than leaving
+the absence to be discovered later.
+
+## Using git instead
+
+Installing the CLI also installs `git-remote-coderook`, so git talks to
+CodeRook directly — both ways:
+
+```
+git clone coderook://my-project
+git push coderook main
+git fetch
+```
+
+It exists so that every editor's built-in git panel works with CodeRook
+without a plugin. If you are not already living in git, `cbx submit` is
+the simpler tool and this is not an upgrade on it.
+
+**Pushing.** Each commit becomes a version, oldest first, with its message
+kept. Later pushes send only what is new, so the usual case — a few commits —
+is quick; a first push of a long history is not, and the helper says how many
+commits it is about to publish before it starts. Branches become lines, and a
+branch pushed for the first time starts from the commit it forked at rather
+than from wherever the project happens to be.
+
+**Cloning and fetching.** Every version becomes a commit, keeping its message,
+its date and who published it. This works on any project, including one that
+has never been near git — a project built entirely with `cbx submit`
+clones into a normal git history. A fetch only downloads versions this clone
+does not already have.
+
+**What it does not do:**
+
+| | |
+| --- | --- |
+| Tag kind | A lightweight tag comes back annotated. CodeRook records a name, not which sort of tag made it. |
+| Force pushes, branch deletion | Refused — versions are immutable, so there is nothing to rewind to. |
+| Submodules | Skipped on push, and it says which paths. |
+| The executable bit | Everything arrives as a normal file. A script cloned back needs `chmod +x`. |
+
+**On round trips.** Push then clone gives you back the same *files*, not the
+same *commit ids*. A commit id covers its author, committer and timestamps,
+and CodeRook records who published a version rather than the original stamps —
+so the history you get back is a faithful copy of the contents and an honest
+approximation of the commits. Two people cloning the same project do get
+identical ids as each other.
+
+Merges are asymmetric for the same reason. A publish states one base version,
+so pushing a git merge records one parent and the fork is lost — the merged
+tree is exact, the shape is not. Reading back is richer: a version that really
+has two parents is rebuilt as a real git merge.
+
+Each version records the commit it came from, so a colleague pushing the same
+project does not republish history the project already holds. Pushing a git
+history into a project whose versions came from somewhere else is refused
+rather than interleaved.
+
+### The names are the same
+
+There is no translation table to learn, because there is nothing to translate.
+The commands carry git's names:
+
+```
+cbx push          cbx pull          cbx clone
+cbx log           cbx status        cbx branch
+cbx checkout      cbx merge         cbx tag
+```
+
+Each is the CodeRook command it always was, reachable by the name a git user
+would reach for: `push` is `submit`, `pull` is `get`, `log` is `versions`,
+`branch` is `tracks`, `checkout` is `track`, `tag` is `release`. The original
+names still work and mean the same thing.
+
+That is also what the git remote does. `git push` performs the operation
+`cbx push` performs — the same code decides what changed, the same code
+publishes it. The remote is a way to reach these commands from git, not a
+second implementation of them that happens to agree.
+
+**What does not appear on that list**, because git has no such idea and
+inventing one would be pretending: `projects`, `delete`, `people`, `watch`,
+`issues`, `propose`, `proposals`, `actions`, `runs`, `logs`, `runner`,
+`tokens`, `licence`, `ai`. Use
+them by name; nothing about them changes when a version arrives through git.
+
+`git commit` has no CodeRook equivalent either, and should not: it is local to
+git, and a version is not made until something is published.
+
+### Tags and releases
+
+`git push --tags` publishes each tag as a release, because that is the same
+statement in the other vocabulary — the service puts it plainly: *"a release
+is a Version with a name on it, not a different kind of object."*
+
+```
+git tag -a v1.0 -m "First stable release"
+git push coderook v1.0
+```
+
+The tag names the version its commit already became; it does not publish
+anything, so push the branch first. An annotated tag's message becomes the
+release notes and a lightweight tag brings none — the commit's own message is
+deliberately *not* used, since nobody wrote it about the release.
+
+Cloning reverses it: every release comes back as a tag on the right commit.
+
+From the command line, `cbx release v1.0` names the newest save the same way,
+and `cbx notes 41 --edit` writes its release notes.
+
+Assets are separate and unaffected. They attach to a version from a run's
+artifacts or with `cbx attach <file>`, so a release made by pushing a tag
+simply has none until something adds them — which is what a release without a
+build has always looked like.
+
+## Bundles
+
+```
+cbx bundle                    pack this project as <name>.cbx
+cbx unbundle backup.cbx       extract one
+cbx inspect backup.cbx        see what it holds  (--files to list them)
+```
+
+A `.cbx` is the CodeBox bundle format: content-defined chunks, Zstandard where
+it helps, raw where it does not, and a SHA-256 for every chunk and file.
+Extraction is verified and atomic — a damaged bundle fails rather than leaving
+a half-written tree.
+
+## Claude Code
+
+Run this **in a terminal**, not inside Claude Code:
+
+```bash
+cbx skill
+```
+
+That is the whole setup. It writes `~/.claude/skills/coderook/SKILL.md`, and
+from then on you ask for what you want in ordinary words:
+
+> save this to CodeRook
+
+> what have I changed?
+
+> what versions does this project have?
+
+Claude works out which commands to run. You can also call it by name with
+`/coderook`.
+
+**The skill is called `coderook`, not `cbx`.** `cbx` is the command line, run
+in a terminal; the skill is the file that teaches Claude how to use it. Typing
+`cbx skill` *into* Claude Code asks it for a skill by that name and it will
+tell you there is not one — which is correct, and is why the line above says
+where to run it.
+
+`cbx skill --project` writes it into `./.claude` instead of your home
+folder, so it travels with the repository and everybody who clones it has it
+too.
+
+Sign in once per machine first — `cbx sign-in` — or set `CODEROOK_TOKEN`
+in automation. The skill will not save anything without asking you first, and
+never deletes.
+
+## Installing it as a plugin instead
+
+If you would rather not install the command line first, CodeRook publishes a
+plugin marketplace of its own:
+
+```
+/plugin marketplace add https://coderook.com/marketplace.json
+/plugin install coderook@coderook
+```
+
+That fetches the same package from npm and brings the skill with it. The
+marketplace is a plain file on coderook.com rather than a git repository, so
+there is no repository to clone and no second account anywhere.
+
+One thing to know: a plugin install puts the package in Claude Code's plugin
+folder, not on your `PATH`. The skill copes with that on its own by falling
+back to `npx -y @coderook/cli`, but `npm install --global @coderook/cli` is
+faster if you plan to run commands yourself as well.
+
+## A structured connection instead
+
+The skill teaches Claude the command line, which needs no configuration. If you
+would rather it had structured tools, there is an MCP server as well. It works
+with Codex too, which is the reason it exists.
+
+Claude Code:
+
+```
+claude mcp add --scope user coderook -- npx -y @coderook/cli mcp
+```
+
+Codex, in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.coderook]
+command = "npx"
+args = ["-y", "@coderook/cli", "mcp"]
+```
+
+To share it with everyone on a project, commit this beside the code:
+
+```json
+// .mcp.json
+{
+  "mcpServers": {
+    "coderook": {
+      "command": "npx",
+      "args": ["-y", "@coderook/cli", "mcp"]
+    }
+  }
+}
+```
+
+It offers five things, all of which read: your projects, a project's versions,
+the files in a version, one file's contents at a version, and what has changed
+in a local folder. It cannot save, delete, or sign in or out.
+
+## Checking things
+
+```
+cbx doctor
+```
+
+Reports the tool's version, where its configuration lives, whether the service
+is reachable, and who this machine is signed in as.
+
+## Exit codes
+
+`0` on success, `1` on failure. Every command prints why it failed on standard
+error, so a script can branch on the status and log the reason.

package/dist/cli/src/cli.js

@@ -2267,6 +2267,36 @@ const SPECS = [
         ],
         run: project_commands_js_1.commandAi,
     },
+    {
+        /*
+          Not `publish`, which already reaches `submit` and would read as a
+          release. This is who can reach the project, and it is named for that.
+        */
+        name: "visibility",
+        group: "Your projects",
+        summary: "who can reach a project: private, link only or public",
+        usage: "visibility [level] [project]",
+        detail: "The level is public, unlisted or private. With none, says what the\n" +
+            "project is set to now.\n\n" +
+            "Private is you and the people you invite. Unlisted, which the website\n" +
+            "calls link only, keeps it off your profile and out of search. Public\n" +
+            "lists it on your profile, and its page offers the saves somebody named\n" +
+            "and did not hide.\n\n" +
+            "Opening a project up asks first and says what becomes readable: any\n" +
+            "account signed in to CodeRook that has its link can open every save\n" +
+            "through the API, not only the named versions. Going private asks\n" +
+            "nothing.",
+        options: [
+            { flags: "-y, --yes", description: "open it up without asking, for scripts" },
+        ],
+        examples: [
+            "cbx visibility",
+            "cbx visibility public",
+            "cbx visibility unlisted my-project --yes",
+            "cbx visibility private my-project",
+        ],
+        run: project_commands_js_1.commandVisibility,
+    },
     {
         name: "issues",
         group: "Your projects",
@@ -2715,6 +2745,8 @@ const SPECS = [
             { flags: "--theirs", description: "keep theirs" },
             { flags: "--both", description: "keep both" },
             { flags: "--drop", description: "abandon the upload" },
+            { flags: "--path <file>", description: "decide one file rather than every one outstanding" },
+            { flags: "--cancel", description: "call the merge off; your upload stays stored" },
             { flags: "--ask <usernames>", description: "ask people to review it, comma separated" },
         ],
         run: commandMerge,

package/dist/cli/src/config.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DamagedLinkError = exports.credentials = exports.DEFAULT_API = void 0;
 exports.apiOrigin = apiOrigin;
+exports.siteOrigin = siteOrigin;
 exports.configDirectory = configDirectory;
 exports.storeToken = storeToken;
 exports.loadToken = loadToken;
@@ -33,6 +34,26 @@ exports.DEFAULT_API = "https://api.coderook.com";
 function apiOrigin() {
     return (process.env.CODEROOK_API_URL || exports.DEFAULT_API).replace(/\/+$/, "");
 }
+/**
+ * The website that goes with the service, for a link somebody can open.
+ *
+ * Derived rather than configured: the service answers on `api.` in front of
+ * the site's own host, so taking that off gives the address people use. A
+ * service anywhere else — a local one on a port — has no site this can name,
+ * and null says so rather than printing a link that goes nowhere.
+ */
+function siteOrigin(api = apiOrigin()) {
+    try {
+        const url = new URL(api);
+        if (!url.hostname.startsWith("api."))
+            return null;
+        url.hostname = url.hostname.slice("api.".length);
+        return url.origin;
+    }
+    catch {
+        return null;
+    }
+}
 /** The per-user configuration directory, per platform convention. */
 function configDirectory() {
     if (process.env.CODEROOK_CONFIG_DIR)

package/dist/cli/src/project_commands.js

@@ -14,8 +14,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveProject = resolveProject;
 exports.commandAi = commandAi;
+exports.readLevel = readLevel;
+exports.splitVisibility = splitVisibility;
+exports.offeredPublicly = offeredPublicly;
+exports.commandVisibility = commandVisibility;
 exports.commandVersions = commandVersions;
 const node_process_1 = __importDefault(require("node:process"));
+const promises_1 = require("node:readline/promises");
 const api_js_1 = require("./api.js");
 const config_js_1 = require("./config.js");
 const dim = (value) => `${value}`;
@@ -121,6 +126,207 @@ async function commandAi(parsed) {
     console.log(dim("one that refuses model training."));
     return 0;
 }
+/**
+ * Who can reach a project, in the order the site shows them.
+ *
+ * The service calls the middle one `unlisted` and the website calls it "Link
+ * only"; both are accepted, and the prose uses the website's words.
+ */
+const LEVELS = [
+    ["private", "private", "you and the people you invite"],
+    [
+        "unlisted",
+        "link only",
+        "not listed anywhere; any account signed in with its link can read it",
+    ],
+    [
+        "public",
+        "public",
+        "listed on your profile and in search; its page offers the named versions",
+    ],
+];
+const wordFor = (level) => LEVELS.find(([name]) => name === level)?.[1] ?? level;
+/** A typed word as a level, or null when it is not one. */
+function readLevel(word) {
+    const text = (word ?? "").trim().toLowerCase();
+    if (text === "link" || text === "link-only")
+        return "unlisted";
+    const found = LEVELS.find(([name]) => name === text);
+    return found ? found[0] : null;
+}
+/**
+ * `[level] [project]`, both optional.
+ *
+ * The level is recognised by being one, so `cbx visibility my-project` asks
+ * and `cbx visibility public` changes. Two words where the first is not a
+ * level is a mistyped level rather than a project, and is said so — reading
+ * it as a project would answer "no project matching" to somebody who typed
+ * "pubic".
+ */
+function splitVisibility(positional) {
+    const [first, second] = positional;
+    const level = readLevel(first);
+    if (level)
+        return { level, project: second };
+    if (second !== undefined) {
+        return {
+            error: `"${first}" is not a visibility. Pick public, unlisted or private.`,
+        };
+    }
+    return { project: first };
+}
+/**
+ * The versions a public page offers, by the service's own rule.
+ *
+ * Named, not hidden, finished arriving and not taken down — the four things
+ * `public_rule.ts` asks. Counted here so the question before a project goes
+ * public can say what the page will show rather than describe it.
+ */
+function offeredPublicly(saved) {
+    return saved.filter((one) => Boolean(one.name) &&
+        one.visibility === "public" &&
+        one.state === "verified" &&
+        !one.removedAt);
+}
+/**
+ * The public page's address, once it answers.
+ *
+ * Asked of the service rather than assembled, because the page lives under
+ * the owner's name and the owner is not always the person running this — a
+ * collaborator can open up somebody else's project. A link is printed only
+ * when the public side has confirmed it is the same project.
+ */
+async function publicAddress(project) {
+    const site = (0, config_js_1.siteOrigin)();
+    if (!site)
+        return null;
+    const me = await (0, api_js_1.whoami)().catch(() => null);
+    if (!me?.username)
+        return null;
+    const found = await (0, api_js_1.findPublicProject)(me.username, project.slug);
+    if (found?.id !== project.id)
+        return null;
+    return `${site}/${encodeURIComponent(me.username)}/${encodeURIComponent(project.slug)}`;
+}
+/** A plain yes or no, where anything but yes is no. */
+async function agreed(question) {
+    const prompt = (0, promises_1.createInterface)({
+        input: node_process_1.default.stdin,
+        output: node_process_1.default.stdout,
+    });
+    const typed = await prompt.question(question);
+    prompt.close();
+    return /^y(es)?$/i.test(typed.trim());
+}
+/**
+ * Show or change who can reach a project.
+ *
+ * Opening one up asks first and says what becomes readable, because that is
+ * the step that cannot be taken back — somebody may already have read it by
+ * the time it is private again. Closing one asks nothing: it takes nothing
+ * from anybody who should have it.
+ */
+async function commandVisibility(parsed) {
+    const asked = splitVisibility(parsed.positional);
+    if (asked.error) {
+        console.error(red(asked.error));
+        return 1;
+    }
+    const project = await resolveProject(asked.project);
+    if (!project)
+        return 1;
+    const current = readLevel(project.visibility) ?? "private";
+    if (!asked.level) {
+        console.log(`${bold(project.name)} is ${accent(wordFor(current))}.`);
+        for (const [level, , meaning] of LEVELS) {
+            const mark = level === current ? accent("›") : " ";
+            console.log(`  ${mark} ${level.padEnd(9)} ${dim(meaning)}`);
+        }
+        if (current === "public") {
+            const address = await publicAddress(project);
+            if (address)
+                console.log(`\n  ${address}`);
+        }
+        console.log("");
+        console.log(dim(`Change it with: cbx visibility <level>` +
+            (asked.project ? ` ${asked.project}` : "")));
+        return 0;
+    }
+    const target = asked.level;
+    if (target === current) {
+        const address = target === "public" ? await publicAddress(project) : null;
+        console.log(`${project.name} is already ${wordFor(target)}` +
+            (address ? `: ${address}` : "."));
+        return 0;
+    }
+    const sure = parsed.flags.get("yes") === true || parsed.flags.get("y") === true;
+    const asking = target !== "private" && !sure;
+    /*
+      Refused rather than asked when nobody can answer. A prompt on a pipe
+      either hangs a script for ever or reads an empty line as no, and neither
+      tells whoever wrote the script what to do about it.
+    */
+    if (asking && !node_process_1.default.stdin.isTTY) {
+        console.error(red(`Making ${project.name} ${wordFor(target)} needs a yes, and nobody is here to give one.`));
+        console.error(dim("  Run it in a terminal to be asked, or add --yes."));
+        return 1;
+    }
+    const offered = target === "public" ? offeredPublicly(await (0, api_js_1.versions)(project.id)) : [];
+    if (asking) {
+        if (target === "public") {
+            console.log(`Making ${bold(project.name)} public lists it on your profile and in search.`);
+            if (offered.length) {
+                const names = offered.slice(0, 5).map((one) => one.name).join(", ");
+                const more = offered.length > 5 ? ` and ${offered.length - 5} more` : "";
+                console.log(`  Its page offers ${offered.length} named version${offered.length === 1 ? "" : "s"}: ${names}${more}.`);
+            }
+            else {
+                console.log("  Its page will be empty until a save is named — cbx promote does that.");
+            }
+            console.log(dim("  Saves nobody named, and versions you hid, are not on the page."));
+        }
+        else {
+            console.log(`Making ${bold(project.name)} link only keeps it off your profile and out of search.`);
+        }
+        /*
+          Said because it is true today, not because it is the design. The public
+          page follows the named-versions rule; the signed-in routes let any
+          account read an unlisted or public project whole, commits and hidden
+          versions included. Somebody deciding whether to open a project up
+          should be deciding about that.
+        */
+        console.log(dim("  Any account signed in to CodeRook that has its link can open every save\n" +
+            "  through the API, not only the named versions. Check the history holds\n" +
+            "  nothing you would not share."));
+        if (!(await agreed(`Make ${project.name} ${wordFor(target)}? [y/N] `))) {
+            console.log(dim(`Nothing changed. ${project.name} is still ${wordFor(current)}.`));
+            return 1;
+        }
+    }
+    try {
+        await (0, api_js_1.updateProject)(project.id, { visibility: target });
+    }
+    catch (error) {
+        console.error(red(error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+    if (target === "public") {
+        const address = await publicAddress(project);
+        console.log(green(`${project.name} is now public`) + (address ? `: ${address}` : "."));
+        console.log(dim(offered.length
+            ? `  Its page offers ${offered.length} named version${offered.length === 1 ? "" : "s"}.`
+            : "  Its page is empty until a save is named — cbx promote does that."));
+    }
+    else if (target === "unlisted") {
+        console.log(green(`${project.name} is now link only.`));
+        console.log(dim("  It is not listed anywhere; any account signed in with its link can read it."));
+    }
+    else {
+        console.log(green(`${project.name} is now private.`));
+        console.log(dim("  Only you and the people you invite can reach it."));
+    }
+    return 0;
+}
 /** Every saved version of a project, newest first. */
 async function commandVersions(parsed) {
     const project = await resolveProject(parsed.positional[0]);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@coderook/cli",
-  "version": "0.31.8",
-  "description": "CodeRook from the command line, on any operating system",
+  "version": "0.31.10",
+  "description": "The command line for CodeRook (coderook.com): version control and project hosting for projects of any size. Every save is a compressed snapshot, private or public, never used to train AI.",
   "license": "SEE LICENSE IN LICENSE.txt",
   "homepage": "https://coderook.com",
   "bugs": {
@@ -9,9 +9,15 @@
   },
   "keywords": [
     "coderook",
+    "cbx",
+    "version-control",
+    "vcs",
     "versioning",
+    "project-hosting",
     "backup",
-    "cbx"
+    "snapshots",
+    "large-files",
+    "gamedev"
   ],
   "engines": {
     "node": ">=20.11.0"

package/skills/coderook/SKILL.md

@@ -103,6 +103,18 @@ 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.
 
+## Who can reach a project
+
+```bash
+cbx visibility                 # what it is now: private, unlisted or public
+cbx visibility public --yes    # list it on the owner's profile
+cbx visibility private         # back to the people invited
+```
+
+**Never make a project public or unlisted unless the person has asked for
+exactly that.** `--yes` skips the question the command would otherwise ask
+them, so only pass it once they have answered it. Going private is always safe.
+
 ## When two saves collide
 
 If somebody saved while this folder was behind, the second save becomes a merge