@brainbase-labs/cli 0.47.0 → 0.49.0

package/README.md

@@ -27,6 +27,24 @@ brainbase benchmark list        # list benchmarks for the linked agent
 
 Run `brainbase help` to see every command.
 
+## Agent surfaces
+
+Manage Chat, Slack, Meetings, GitHub, Linear and Phone from the terminal:
+
+```sh
+brainbase agent connections --agent <id> --json
+brainbase agent surface chat configure --agent <id> --models= --json
+brainbase agent surface meeting configure --agent <id> --vision true
+brainbase agent surface github connect --agent <id> --no-open
+brainbase agent surface --help
+```
+
+Use `status` for effective settings and capabilities, and `configure` to
+change only the supplied fields. GitHub/Linear setup prints portable browser
+links and can resume with `wait --installation <id>`. Provider operations
+require a login session. Phone purchases and all new disconnect commands
+require `--yes`. See the [command reference](docs/reference/commands.mdx#connections).
+
 ## Link and pull in one step
 
 A fresh checkout — a task sandbox, a CI job — can attach to an agent and pull it
@@ -336,7 +354,7 @@ Playbook files carry a small YAML frontmatter (`title`, `description`) — the C
 | `BRAINBASE_API_URL` | Legacy KLS host override. Control requests use `/api/cli`; it is also the fallback for model-proxy and registry traffic. |
 | `BRAINBASE_PROXY_URL` | Override the model-proxy host used when enabling harness tracking. |
 | `BRAINBASE_REGISTRY_URL` | Override the registry API host. |
-| `BRAINBASE_TOKEN` | Use a PAT instead of the stored login session. The only way a PAT authenticates a control-plane command — see [Auth](#auth). |
+| `BRAINBASE_TOKEN` | Use a PAT instead of the stored login session. Outranks both the session and the PAT saved in `token.json`. See [Auth](#auth). |
 | `BRAINBASE_HOME` | Where local state lives (default: `~/.brainbase`) |
 
 Model-proxy and registry traffic fall back through `BRAINBASE_API_URL`,
@@ -344,30 +362,26 @@ the server captured at login, and finally `https://api.v1.brainbaselabs.com`.
 
 ## Auth
 
-Three credentials, and which ones a command considers depends on the service
-it talks to:
+Every command tries three credentials, in this order:
 
-| Commands | Credentials tried, in order |
-|-|-|
-| `agent`, `orchestration`, `link`, `unlink`, `sync`, `status`, `team` | `BRAINBASE_TOKEN`, then the `auth.json` session |
-| `template`, `skill`, `token` | `BRAINBASE_TOKEN`, then the session, then `token.json` |
-| `task` commands | `BRAINBASE_TOKEN`, then the session, then `token.json` — the last only when no session is configured |
-| `benchmark` control-plane commands | `BRAINBASE_TOKEN`, then the session |
+1. `BRAINBASE_TOKEN`
+2. the `auth.json` login session, renewed first if it has expired
+3. the PAT that `brainbase token create` saved in `~/.brainbase/token.json`,
+   when there is no session or it could not be renewed. A PAT minted by a
+   different account than the session is never used in its place.
 
-`brainbase whoami` (or `--json`) reports which one is active.
+`brainbase whoami` (or `--json`) reports which one is active. It renews an
+expired session itself, so what it reports is what the next command will use.
 
-**For CI:** `brainbase token create` saves the PAT to `~/.brainbase/token.json`,
-and control-plane commands never read that file — `brainbase agent push` needs
-the token in `BRAINBASE_TOKEN`:
+**For CI:** a runner has no `token.json`, so hand it the PAT as a secret:
 
 ```bash
 export BRAINBASE_TOKEN=bbpat_…
 brainbase agent push
 ```
 
-Do not bake a `~/.brainbase` directory into a build image: a leftover
-`auth.json` outranks the stored PAT, and every control-plane command starts
-failing once its session expires.
+Do not bake a `~/.brainbase` directory into a build image. Ship
+`BRAINBASE_TOKEN` as a secret instead.
 
 An explicit PAT does not inherit routing from a stored login. Set
 `BRAINBASE_CONTROL_PLANE_URL` when using a PAT against a non-default MAS host.