@whittlelabs/sifter 0.30.7 → 0.30.8

package/README.md

@@ -4,14 +4,30 @@ The Whittle Sifter is a paired AI reviewer for [Whittle Sift](https://sift.whitt
 
 ## Install
 
-`@whittlelabs/sifter` is published publicly to npmjs.com (released by the
-delivery pipeline on a version bump):
+The Sifter runs on macOS, Linux, and Windows through WSL. Native Windows is not supported: install [WSL](https://learn.microsoft.com/windows/wsl/install) and run everything below inside it.
+
+It needs three things on the machine first:
+
+| Prerequisite | Version | How to get it |
+|---|---|---|
+| Node.js | 20 or newer | [nodejs.org](https://nodejs.org), or a version manager such as [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) |
+| git | 2.20 or newer | macOS: `xcode-select --install` (or Homebrew). Linux and WSL: your package manager, e.g. `sudo apt install git` |
+| Claude Code | 2.0 or newer, signed in | `npm install -g @anthropic-ai/claude-code`, then run `claude` once and sign in |
+
+On a Mac without the Command Line Tools, `/usr/bin/git` is only a placeholder that asks for them. The Sifter treats that as git not working, so install them first.
+
+Then install the Sifter from npm:
 
 ```bash
 npm install -g @whittlelabs/sifter
 ```
 
-Requires Node 20+.
+If that fails with `EACCES`, do not reach for `sudo`. npm is trying to write into a system directory; install Node through a version manager (which puts global packages in your home directory), or point npm at a directory you own:
+
+```bash
+npm config set prefix ~/.npm-global
+export PATH="$HOME/.npm-global/bin:$PATH"   # add this line to your shell profile too
+```
 
 ## Pair
 
@@ -21,6 +37,8 @@ Visit Sift's **Settings → Pair a Sifter**. Sift will display a pairing code an
 whittle-sifter init --pairing-code=ABCD-1234
 ```
 
+Before it spends the code, `init` checks what `run` will need: git, Claude Code, and a config directory and run root it can write to. If anything is missing it says what and stops with the code unspent, so fix it and run the same command again. Nothing is saved on your machine unless pairing succeeds all the way through.
+
 The Sifter defaults to production. To pair against another Whittle Labs environment, name it with `--profile`: the name selects the backend as well as the directory the pairing lands in.
 
 ```bash
@@ -65,7 +83,7 @@ The Sifter subscribes to your job pool and waits for review jobs. Leave it runni
 whittle-sifter doctor
 ```
 
-Fifteen checks over everything the Sifter needs before it can review anything: your pairing, your config, `git`, the `claude` CLI and its login, a writable run root, free disk, and whether Sift can be reached. One line per check, with a remedy under anything that failed. It exits 4 if something is wrong and 0 otherwise, so it works in a script.
+Sixteen checks over everything the Sifter needs before it can review anything: a supported platform and Node version, your pairing, your config, `git`, the `claude` CLI and its login, a writable run root, free disk, and whether Sift can be reached. One line per check, with a remedy under anything that failed, and each problem reported once: a check that depends on one that failed is skipped and points back at it. It exits 4 if something is wrong and 0 otherwise, so it works in a script.
 
 `init` and `run` run the relevant subset themselves, so `doctor` is for when the Sifter looks healthy and nothing is happening.
 
@@ -74,6 +92,16 @@ whittle-sifter doctor --deep     # also spend one real turn proving the claude l
 whittle-sifter doctor --json     # the verdicts as JSON, and nothing else
 ```
 
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | A fatal error; the message says what went wrong |
+| 2 | This version is older than Sift accepts: `npm install -g @whittlelabs/sifter@latest` |
+| 3 | The pairing was revoked (removed in Sift, or replaced by a newer pairing): pair again |
+| 4 | A pre-flight check failed; the report above it names the remedy |
+
 ## Other commands
 
 ```bash