@brainbase-labs/cli 0.21.2 → 0.23.0

package/README.md

@@ -144,7 +144,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 |
+| `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_HOME` | Where local state lives (default: `~/.brainbase`) |
 
 Model-proxy and registry traffic fall back through `BRAINBASE_API_URL`,
@@ -152,11 +152,29 @@ the server captured at login, and finally `https://api.v1.brainbaselabs.com`.
 
 ## Auth
 
-Managed task creation uses this authentication precedence:
+Three credentials, and which ones a command considers depends on the service
+it talks to:
 
-1. `BRAINBASE_TOKEN` — an explicit PAT from the environment.
-2. `brainbase login` — a Supabase session stored in `~/.brainbase/auth.json`.
-3. `brainbase token create --scopes read,publish` — a PAT stored in `~/.brainbase/token.json` when no login session is configured.
+| 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 create` | `BRAINBASE_TOKEN`, then the session, then `token.json` — the last only when no session is configured |
+
+`brainbase whoami` (or `--json`) reports which one is active.
+
+**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`:
+
+```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.
 
 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.