@coderook/cli 0.31.7 → 0.31.9

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

package/README.md

@@ -1,389 +1,401 @@
-# 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.
+
+## 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.

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

@@ -19,6 +19,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const faults_js_1 = require("./faults.js");
 const identify_js_1 = require("./identify.js");
 const worktree_js_1 = require("./worktree.js");
+const rules_js_1 = require("./rules.js");
 const publish_name_js_1 = require("./publish_name.js");
 const compress_js_1 = require("./compress.js");
 const compression_policy_js_1 = require("../shared/compression_policy.js");
@@ -142,6 +143,8 @@ class Uploader {
      */
     plannedLayouts = new Map();
     plannedQuote = null;
+    /** Files sent only because git tracks them; named in the save so the service allows them. */
+    trackedByGit = [];
     /*
       Digests worked out while planning, so sending does not work them out again.
   
@@ -407,6 +410,13 @@ class Uploader {
         const rules = request.allowIgnored
             ? { shared: "", local: "" }
             : await (0, worktree_js_1.readRules)(request.localPath);
+        /*
+          What the survey keeps only because git tracks it, named for the
+          service: its own check of the rules would otherwise refuse them as a
+          rule this client forgot. See gitTracked.
+        */
+        this.trackedByGit = [];
+        const tracked = request.allowIgnored ? null : await (0, worktree_js_1.gitTracked)(request.localPath);
         /*
           Surveyed, not listed.
     
@@ -443,6 +453,12 @@ class Uploader {
             percent: 6,
             bytesPerSecond: 0,
         })));
+        if (tracked) {
+            const layers = await (0, worktree_js_1.collectLayers)(request.localPath, rules);
+            this.trackedByGit = everything
+                .map((file) => file.path)
+                .filter((file) => tracked.files.has(file) && (0, rules_js_1.excludes)(file, false, layers));
+        }
         (0, profile_js_1.counted)("files surveyed", everything.length);
         const unticked = new Set(request.excluded ?? []);
         const ticked = request.excluded
@@ -854,6 +870,7 @@ class Uploader {
                     : { expectedHeadVersionId: request.expectedHeadVersionId }),
                 ...(request.track ? { track: request.track } : {}),
                 ...(request.allowIgnored ? { allowIgnored: true } : {}),
+                ...(this.trackedByGit.length ? { trackedByGit: this.trackedByGit } : {}),
                 ...(request.allowSecrets ? { allowSecrets: true } : {}),
                 ...(request.linesAdded === undefined ? {} : { linesAdded: request.linesAdded }),
                 ...(request.linesRemoved === undefined

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

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IGNORE_HEADING = exports.KEEP_HEADING = exports.LOCAL_EXCLUDE_FILE = exports.IGNORE_FILE = exports.STARTER_IGNORE = exports.CODEROOK_TAIL = exports.CODEROOK_TAIL_HEADING = exports.KEPT_ANYWAY = exports.KEPT_ANYWAY_HEADING = exports.ALSO_LEFT_OUT = exports.ALSO_LEFT_OUT_HEADING = exports.STARTER_MARKER = exports.EVALUATION_FILE_LIMIT = void 0;
+exports.IGNORE_HEADING = exports.KEEP_HEADING = exports.TRACKED_BY_GIT = exports.LOCAL_EXCLUDE_FILE = exports.IGNORE_FILE = exports.STARTER_IGNORE = exports.CODEROOK_TAIL = exports.CODEROOK_TAIL_HEADING = exports.KEPT_ANYWAY = exports.KEPT_ANYWAY_HEADING = exports.ALSO_LEFT_OUT = exports.ALSO_LEFT_OUT_HEADING = exports.STARTER_MARKER = exports.EVALUATION_FILE_LIMIT = void 0;
 exports.ruleTarget = ruleTarget;
 exports.keptTargets = keptTargets;
 exports.withoutOpposites = withoutOpposites;
@@ -11,6 +11,7 @@ exports.starterAuthored = starterAuthored;
 exports.missingStarterRules = missingStarterRules;
 exports.missingEngineRules = missingEngineRules;
 exports.isRepository = isRepository;
+exports.gitTracked = gitTracked;
 exports.migrateRetiredRules = migrateRetiredRules;
 exports.starterFor = starterFor;
 exports.moveRule = moveRule;
@@ -404,6 +405,39 @@ async function isRepository(root) {
         return false;
     }
 }
+/** The label a file kept because git tracks it carries, where a rule would be. */
+exports.TRACKED_BY_GIT = "(tracked by git)";
+/**
+ * The files git tracks here, which an ignore rule does not take away.
+ *
+ * Git applies .gitignore only to files it does not track yet. Once a file is
+ * committed, a rule written later — or a broad one like `storage/` that also
+ * matches a source folder three levels down — leaves it exactly where it is.
+ * This applied the rules to everything, so a project whose .gitignore said
+ * `storage/` arrived without `internal/storage/*.go`: in git, whole; on
+ * CodeRook, missing the six files that made it build.
+ *
+ * Null when the folder is not a repository, or git cannot be asked — then the
+ * rules alone decide, as they always did.
+ */
+async function gitTracked(root) {
+    if (!(await isRepository(root)))
+        return null;
+    const listed = await git(root, "ls-files", "-z");
+    if (listed === null)
+        return null;
+    const files = new Set(listed.split(String.fromCharCode(0)).filter(Boolean));
+    const folders = new Set();
+    for (const file of files) {
+        for (let cut = file.lastIndexOf("/"); cut > 0; cut = file.lastIndexOf("/", cut - 1)) {
+            const folder = file.slice(0, cut);
+            if (folders.has(folder))
+                break;
+            folders.add(folder);
+        }
+    }
+    return { files, folders };
+}
 /**
  * Convert the rules an earlier build wrote into one .gitignore.
  *
@@ -519,6 +553,15 @@ async function moveRule(root, file, keep) {
     const directory = await (0, promises_1.stat)(node_path_1.default.join(root, bare))
         .then((entry) => entry.isDirectory())
         .catch(() => file.endsWith("/"));
+    /*
+      A file git tracks cannot be ignored by a rule — git keeps it, and so does
+      this. Writing the rule anyway would look like it worked and change
+      nothing, so it is refused with what would actually leave it out.
+    */
+    if (!keep && !directory && (await gitTracked(root))?.files.has(bare)) {
+        throw new Error(`git tracks ${bare}, so a rule cannot leave it out. Untick it for one ` +
+            `save, or stop git tracking it: git rm --cached "${bare}"`);
+    }
     const target = directory ? `${bare}/` : bare;
     const line = keep ? `!${target}` : target;
     /*
@@ -885,6 +928,8 @@ stats,
 /** Filled with how much of the folder the cap allowed through. */
 outcome) {
     const layers = await collectLayers(root, rules);
+    /* What git already tracks goes up whatever a rule says; see gitTracked. */
+    const tracked = await gitTracked(root);
     const files = [];
     const present = new Set();
     const pending = [root];
@@ -926,7 +971,9 @@ outcome) {
                 // Skipping an excluded directory outright is what keeps this fast,
                 // but a `!` rule exists to rescue what is inside one, so the subtree
                 // is only skipped when no negation could reach into it.
-                if ((0, rules_js_1.excludes)(relative, true, layers) && !(0, rules_js_1.negationReachesInto)(relative, layers)) {
+                if ((0, rules_js_1.excludes)(relative, true, layers) &&
+                    !(0, rules_js_1.negationReachesInto)(relative, layers) &&
+                    !tracked?.folders.has(relative)) {
                     continue;
                 }
                 pending.push(full);
@@ -934,7 +981,7 @@ outcome) {
             }
             if (!entry.isFile())
                 continue;
-            if ((0, rules_js_1.excludes)(relative, false, layers))
+            if ((0, rules_js_1.excludes)(relative, false, layers) && !tracked?.files.has(relative))
                 continue;
             wanted.push({ full, relative });
         }
@@ -1060,6 +1107,7 @@ async function surveyFiles(root, rules,
 */
 onFound) {
     const layers = await collectLayers(root, rules);
+    const tracked = await gitTracked(root);
     const found = [];
     /*
       A level at a time, eight in flight.
@@ -1094,7 +1142,8 @@ onFound) {
                     const relative = node_path_1.default.relative(root, full).split(node_path_1.default.sep).join("/");
                     if (entry.isDirectory()) {
                         if ((0, rules_js_1.excludes)(relative, true, layers) &&
-                            !(0, rules_js_1.negationReachesInto)(relative, layers)) {
+                            !(0, rules_js_1.negationReachesInto)(relative, layers) &&
+                            !tracked?.folders.has(relative)) {
                             continue;
                         }
                         next.push(full);
@@ -1102,7 +1151,7 @@ onFound) {
                     }
                     if (!entry.isFile())
                         continue;
-                    if ((0, rules_js_1.excludes)(relative, false, layers))
+                    if ((0, rules_js_1.excludes)(relative, false, layers) && !tracked?.files.has(relative))
                         continue;
                     here.push({ full, relative });
                 }
@@ -1408,6 +1457,7 @@ function relativeTo(root, full) {
  */
 async function evaluateRules(root, rules, options = {}) {
     const layers = await collectLayers(root, rules);
+    const tracked = await gitTracked(root);
     const impactBytes = new Map();
     const impactFiles = new Map();
     const excluded = [];
@@ -1449,6 +1499,18 @@ async function evaluateRules(root, rules, options = {}) {
             });
             continue;
         }
+        if (rule && tracked?.files.has(relative)) {
+            /*
+              A rule matches it, and git tracks it, so it goes up regardless — and
+              is listed with what kept it, beside the files a `!` rule keeps.
+            */
+            keptFiles += 1;
+            keptBytes += size;
+            uploadFiles += 1;
+            uploadBytes += size;
+            excluded.push({ path: relative, bytes: size, rule: exports.TRACKED_BY_GIT, forceKept: true });
+            continue;
+        }
         if (rule) {
             skippedFiles += 1;
             skippedBytes += size;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@coderook/cli",
-  "version": "0.31.7",
-  "description": "CodeRook from the command line, on any operating system",
+  "version": "0.31.9",
+  "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"