bitfolk 0.1.9 → 0.1.11

package/README.md

@@ -2,27 +2,30 @@
 
 Lets your [Bitfolk](https://bitfolk.ai) workspace start Claude Code, Codex, OpenCode and Hermes sessions on your own
 computer. It checks in without calling a model (a few bytes) and starts a session only when you ask for one, from any
-device. Each session runs as a temporary builder that works one objective and leaves. Every run is recorded on your workspace
-with what it cost.
+device. Each coding tool you turn on is a builder in your workspace: an agent with its own name, look, level, memory
+and permissions, that works in sessions on this computer. Every run is recorded on your workspace with what it cost.
 
 ## Install
 
 Needs Node 20 or newer, on macOS or Linux (on Windows, use WSL), and at least one coding tool such as Claude Code or
 Codex, signed in.
 
-Try it without installing:
+One command, from the repo you want builders to work in:
 
 ```
-npx bitfolk@latest login     # link this computer: name it, tick its coding tools, press Allow
-npx bitfolk@latest up        # keep this running; sessions start when your workspace asks
+cd ~/code/app
+npx bitfolk@latest up        # links this computer (press Allow in your browser), then takes sessions until Ctrl-C
 ```
 
+On a computer that isn't linked yet, `up` runs `login` first: name the computer, tick its coding tools, press Allow.
+Each tool you tick becomes a builder in your workspace (Claude Code, Codex, ...), and because you ran it inside a git
+repo, builders work there, each session in its own worktree and branch (`--no-repo` skips that; `bitfolk repos`
+changes it later).
+
 Or install it to keep it:
 
 ```
 npm i -g bitfolk
-bitfolk login
-bitfolk set --repo ~/code/app        # builders work in their own worktrees of this repo
 bitfolk up
 ```
 
@@ -35,7 +38,7 @@ release rather than reuse one it cached. Installed, it also answers to the short
 |---|---|
 | `bitfolk` | Where things stand: this computer, its workspace, tools on and off, sessions waiting, whether `up` runs (also `bitfolk status`) |
 | `bitfolk login` / `logout` | Link this computer in your browser, or unlink it |
-| `bitfolk up` | Run the sessions your workspace starts, until Ctrl-C (also `bitfolk start`) |
+| `bitfolk up` | Link this computer if it isn't yet, then run the sessions your workspace starts, until Ctrl-C (also `bitfolk start`) |
 | `bitfolk run "<what>"` | Start a session here now, on a new objective, or on an open one with `--goal` (and `--task`) |
 | `bitfolk sessions` | This computer's sessions: waiting, running, and the latest that ended |
 | `bitfolk logs [<id>]` | What a session did: progress, commits, spend, branch; `--follow` to watch it |
@@ -181,14 +184,19 @@ The machine API behind it: `GET /v1/machine/chats`, `GET` and `POST /v1/machine/
 On an objective, press **Run on <computer>**: pick Claude Code or Codex, optionally one task and a note. `bitfolk up` sees it
 on its next check-in (a few bytes, no model) and starts a session:
 
-1. `POST /v1/machine/claim` makes a temporary builder: an agent on that objective, already set up, with a token that ends
-   with the session.
+1. `POST /v1/machine/claim` starts the session as that tool's builder: the same agent every time (it keeps its name,
+   look, level, memory and permissions), joined to the objective, with a token that ends with the session.
 2. The runner starts the tool in the builder's own workspace (a worktree on `bitfolk/builder-<id>` when a repo is
    set) with a work packet that names the objective, the task and your note.
 3. The builder claims the task, works it and reports through `bitfolk-api`, like any agent. Its runs and spend are
    recorded.
-4. `POST /v1/machine/sessions/{id}` reports how it ended. The builder leaves the workspace: its token stops working and
-   unfinished tasks go back on the board. Its branch stays for you to review.
+4. `POST /v1/machine/sessions/{id}` reports how it ended. The session's token stops working and unfinished tasks go
+   back on the board; the builder stays in the workspace, idle until its next session. Its branch stays for you to
+   review.
+
+Besides **Run**, mentioning a builder in an objective chat (`@Claude Code, add a CSV export`) starts a session for it,
+when you (or one of your own agents) write it and the computer is online. Turning a tool off (`bitfolk rm codex`) or
+unlinking the computer removes its builder; turning the tool on again brings it back with its record.
 
 Limits from `bitfolk set` apply to each session; Bitfolk times out a session the runner never reports.
 
@@ -258,7 +266,7 @@ With a GitHub repo, builders' work can go up for review and merge into your main
 bitfolk set --repo ~/code/app --pull-requests on
 ```
 
-1. Connect GitHub in Bitfolk under Tools → Connected apps.
+1. Connect GitHub in Bitfolk under Connectors.
 2. When a session succeeds with commits, the runner pushes its `bitfolk/builder-<id>` branch to the repo's GitHub
    `origin`, with your own git credentials (no prompts, no hooks). Only a GitHub origin is pushed to.
 3. Bitfolk opens a pull request into the branch from `--base` (or origin's default branch, else `main`) through your