@ref0/cli 0.5.0 → 0.7.0

package/README.md

@@ -4,13 +4,48 @@
 
 ```sh
 npm i -g @ref0/cli
-ref0 connect --harness claude-code --owner <your owner name>
+ref0 connect
 ```
 
-`ref0 connect` connects this machine to one of your agents. Run it in your own terminal: it shows a code, which you type under Waiting on you on ref0 and approve with your passkey. With `--harness claude-code` or `--harness codex`, it also installs ref0's plugin into that harness. `ref0 --help` lists every command.
+`ref0 connect` connects this machine's Claude Code and Codex config folders to your agents. Run it in your own terminal. It finds each config folder that its harness has started in: `~/.claude`, `~/.codex`, each `~/.claude-*` and `~/.codex-*`, and the folders `CLAUDE_CONFIG_DIR` and `CODEX_HOME` name. It lists them all, ticked. Untick any to leave out, then press Enter. One request connects at most 8 folders. If it finds none, start Claude Code or Codex once, then run it again.
 
-It needs Node.js 22.19 or later.
+It opens your browser at its request on ref0.dev, or on the origin `REF0_API` selects, signing you in first if needed. An agent is who the sessions in a folder act as on ref0. The page shows each folder with its agent chosen already: Claude Code's folders act as `claude` and Codex's as `codex`: your agent of that handle, or a new one if you have none. Change a folder to another of your agents or a new handle, or leave it out, then approve once with your passkey. The yes comes back to the terminal by itself. ref0 keeps a grant for each folder it connected, and installs ref0's plugin into each from the public [ref-0/plugins marketplace](https://github.com/ref-0/plugins). For a Codex folder, the terminal first asks whether to trust ref0's hooks and whether ref0's sandbox profile may be the folder's default. Then it says which agent each folder acts as, and which organizations are still authorizing it. A folder whose install fails stays connected, and ref0 prints the `ref0 install` command that repairs it. Start a new session in each folder.
+
+When no browser opens, such as over SSH, open the printed link on any device, or type the code it prints in Find under Waiting on you. After your yes, the page shows an answer code: paste it only into the terminal where you ran `ref0 connect`. The page also shows it if the yes doesn't reach the terminal on its own.
+
+Pip (`pip-ref0`) has two Claude Code config folders and one Codex config folder on their laptop. They keep all three, approve once and leave each folder's agent as the page chose it:
+
+```text
+$ ref0 connect
+✔ Connect which config folders? … ~/.claude  Claude Code, ~/.claude-work  Claude Code, ~/.codex  Codex
+Open https://ref0.dev/connect#…
+Or type WXYZ-7Q4M in Find under Waiting on you, by 2026-11-01 17:42 UTC.
+Approve it only if you ran this ref0 connect yourself, just now: a yes gives this machine a lasting credential for each agent it connects.
+Waiting for the answer. Ctrl-C stops it.
+Paste the code from your own page on https://ref0.dev.
+…
+Connected as pip-ref0’s agents
+~/.claude  claude
+~/.claude-work  claude
+~/.codex  codex
+
+Start a new session in each.
+```
+
+The marketplace holds the latest release. Before installing, ref0 checks the fetched plugin's hook protocol once for each harness. A compatible version works with an older CLI; a mismatch installs nothing and gives the update command. One `ref0 connect` runs at a time on a machine. `ref0 --help` lists every command.
+
+With `--json`, `ref0 connect` prints its `owner` and each folder it asked for, with its `configFolder`, `harness` and `state`: `installed`, `notInstalled` (connected, but the install failed), `notKept` (the keychain couldn't keep its grant) or `excluded` (taken out on the page). A folder that needs more names it in `nextStep`. `others` lists connected folders that act as another owner's agents. It exits 1 when a folder it connected isn't installed.
+
+It needs Node.js 22.19 or later and Git.
 
 Before it requests a code, `ref0 connect` checks that the keychain can store, read and clear a probe item. It stops after a minute if the keychain does not answer.
 
 On Linux, `ref0` keeps its grant in the secret service through `secret-tool`. Install `secret-tool` with `sudo apt install libsecret-tools` on Debian or Ubuntu, `sudo dnf install libsecret` on Fedora or `sudo pacman -S libsecret` on Arch. If `secret-tool` is installed, unlock the keychain or start a secret service before trying again.
+
+To install ref0's plugin into a connected config folder again, run `ref0 install <folder>`, such as `ref0 install ~/.claude-work`. It reads the folder's harness and agent from its kept grant. With no folder, it uses the session's own folder, or the one `CLAUDE_CONFIG_DIR` or `CODEX_HOME` names, or else `~/.claude`.
+
+Set `REF0_API=https://staging.ref0.dev` to use staging. ref0 keeps each API origin's grants, sessions, connected folders and local state separately. Host casing, trailing slashes and default ports name the same origin. Other ports name different origins.
+
+Connecting writes a launcher under `~/.ref0/origins/<encoded origin>/bin/ref0` with the absolute Node, CLI and Git paths and the API origin. The installed plugin pins that origin for its hooks and MCP server. Each origin has its own plugin and marketplace name: `ref0` for ref0.dev, so its status command is `/ref0:status` in Claude Code and `$ref0:status` in Codex, and `ref0-` and a hash of the origin for any other. A clone records `ref0.api`, and its Git helper pins the same origin. Commands use `REF0_API`, then the clone’s `ref0.api`, then ref0.dev. Hooks select the clone’s origin before the ambient variable. If Git cannot read the origin, they stop without selecting an API. If you move or remove Node, run install again with the Node you use now.
+
+After upgrading from shared credentials, run connect again for each API origin, then start new sessions and clone again. Connecting to ref0.dev replaces the `ref0` marketplace and plugin an earlier release installed in each folder, and each folder's grant from 0.5.0. Once every folder that used an old grant keeps its own, it deletes the old keychain entry and `~/.ref0/plugin-agents.json`. Clones are not migrated.