@whittlelabs/sifter 0.30.7 → 0.30.9

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
@@ -59,13 +77,25 @@ whittle-sifter run
 
 The Sifter subscribes to your job pool and waits for review jobs. Leave it running in a terminal or wrap it in your favorite process supervisor.
 
+### When something goes away
+
+A running Sifter deals with Sift or `claude` going away on its own, and says what it is doing:
+
+- **Sift can't be reached** (a deploy, a network blip): it logs one warning, keeps trying, and says when Sift is back. This holds at startup too, so starting it during an outage is fine; it begins claiming once Sift answers.
+- **`claude` stops working** (signed out, out of plan, or uninstalled): the review it was running fails with Claude's own message, and the Sifter stops taking new reviews so the rest of your queue waits for you instead of failing. It logs one line saying what to fix, checks again by itself (after 15 seconds at first, backing off to every 5 minutes), and starts claiming again once `claude` works. A check costs nothing while you are signed out, and one short turn once you are back.
+- **Sift needs a newer Sifter**: it finishes the review in hand, installs the newest version with `npm install -g`, and restarts itself. If the install fails, it exits with code 2 and prints the command to run.
+- **The pairing is revoked** (removed in Sift, or replaced by a newer pairing): it exits with code 3 and shows the two ways to pair again. A review it was running goes back to the queue for another Sifter.
+- **It is decommissioned from Sift's settings page**: it finishes the review in hand and exits with code 0.
+
+Ctrl-C stops it at any time, including while it waits.
+
 ## Check
 
 ```bash
 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 +104,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