@tonbo/yield 0.2.2 → 0.3.0

package/README.md

@@ -31,11 +31,11 @@ yield logout
 ## Projects
 
 ```console
-yield connect [folder] [--name <name> | --project <id>] [--account <name>] [--json]
+yield connect [folder] [--name <name> | --project <id>] [--account <name> [--yes]] [--json]
 yield disconnect [folder]
 ```
 
-`connect` binds a folder of this computer to a Project ([ADR-0016](../../apps/user-center/docs/decisions/adr-0016-org-git-workspaces.md) W-18) through `POST /v1/projects/connect`. Without a folder it binds the root of the git work tree you are in, or else the current directory. A git work tree joins the Project of its origin, made when the account has none, so every clone of one origin, on any computer, shares it; a work tree without an origin gets a Project named after its folder. A folder outside git is connected only by naming a new Project (`--name`) or joining one (`--project`). Without `--account` the Project is in your personal account; `--account <name>` binds it to that organization's Project, which needs this computer registered (`yield login`), and logs this computer in to the organization first when it has no login there, without changing the account `tonbo` acts in. A folder connected in another account moves: it is disconnected there first. The folder is named only by a random id kept in `${XDG_STATE_HOME:-$HOME/.local/state}/tonbo-yield/folders.json`; its path never leaves the computer. `disconnect` removes the folder's binding (`DELETE /v1/projects/bindings/<id>`) and leaves the Project. `yield ps` and `yield daemon status` name the current folder's Project. A folder that is not connected stays in your personal account, as before.
+`connect` binds a folder of this computer to a Project ([ADR-0016](../../apps/user-center/docs/decisions/adr-0016-org-git-workspaces.md) W-18) through `POST /v1/projects/connect`. Without a folder it binds the root of the git work tree you are in, or else the current directory. A git work tree joins the Project of its origin, made when the account has none, so every clone of one origin, on any computer, shares it; a work tree without an origin gets a Project named after its folder. A folder outside git is connected only by naming a new Project (`--name`) or joining one (`--project`). Without `--account` the Project is in your personal account; `--account <name>` binds it to that organization's shared team Project, which needs this computer registered (`yield login`), and logs this computer in to the organization first when it has no login there, without changing the account `tonbo` acts in. Before it binds, it says that every session started in the folder from then on is visible in full to every member ([ADR-0017](../../apps/user-center/docs/decisions/adr-0017-projects-forks-visibility.md) D-12) and asks; answering no keeps the folder personal and connects nothing. `--yes` answers for you, and without a terminal nothing is shared unless it is given. A folder connected in another account moves: it is disconnected there first. The folder is named only by a random id kept in `${XDG_STATE_HOME:-$HOME/.local/state}/tonbo-yield/folders.json`; its path never leaves the computer. `disconnect` removes the folder's binding (`DELETE /v1/projects/bindings/<id>`) and leaves the Project. `yield ps` and `yield daemon status` name the current folder's Project. A folder that is not connected stays in your personal account, as before.
 
 ## The device id
 
@@ -84,7 +84,7 @@ After each `turn_end` of a turn that ended in the last 10 minutes, in a cwd insi
 
 ### Routing
 
-Each session goes where its folder's Project says ([ADR-0016](../../apps/user-center/docs/decisions/adr-0016-org-git-workspaces.md) W-7). The daemon reads your folder bindings on this computer in every account it holds a login of, once a minute, and resolves a session's cwd to the nearest connected folder that holds it; a git work tree none of whose folders is connected gets its implicit personal Project, made at its first capture (its origin's, or one named after its root folder). The raw session and every record go to your personal store, and records of a session with a Project name it (`project_id`, `binding_id`); its snapshots go to the Project's repository, as above. A cwd outside every git work tree and every connected folder has no Project, as before. A folder connected to an organization's Project is captured into your personal store with no Project and no snapshot for now: what reaches the organization is being redesigned.
+Each session goes where its folder's Project says ([ADR-0016](../../apps/user-center/docs/decisions/adr-0016-org-git-workspaces.md) W-7). The daemon reads your folder bindings on this computer in every account it holds a login of, once a minute, and resolves a session's cwd to the nearest connected folder that holds it; a git work tree none of whose folders is connected gets its implicit personal Project, made at its first capture (its origin's, or one named after its root folder). The raw session and every record go to your personal store, and records of a session with a Project name it (`project_id`, `binding_id`); its snapshots go to the Project's repository, as above. A cwd outside every git work tree and every connected folder has no Project, as before. A session that starts in a folder connected to an organization's team Project, after it was connected, is the team's ([`capture-v1.json`](../../contracts/sessions/capture-v1.json) `team_session_stream.routing`): its lines go to `session.t.<session id>` in the organization's store with your organization login, its records to the organization's `proc.inbox` in the published form (the device named only by its handle there, paths relative to the folder), and its snapshots to the team Project's repository. Before a line leaves the computer it passes the secret filter ([`secret-patterns-v1.json`](../../contracts/sessions/secret-patterns-v1.json)): keys, tokens, private keys and passwords become `[redacted:<rule>]`, the daemon logs the counts and your own inbox gets a `secret_filter` record, never the text; your local transcript is never changed. A session that started before the folder was connected stays in your personal store, raw, with no Project and no snapshot. Only a yes given on this computer shares: `connect --account` records it in `folders.json` for the binding it was given for, and the team's sessions are those started after both the binding and the yes. A folder connected to an organization before the warning existed shares nothing (its sessions stay personal, with no Project and no snapshot, and the daemon logs why) until you run `yield connect --account <name>` there and answer yes. `yield ps --account <name>` lists the team's sessions, every member's, and `yield session read <id> --account <name>`, `files` and `why` read them.
 
 The daemon uses the saved logins only, the personal account's for everything; `TONBO_API_KEY` does not name a device. One daemon runs per state directory.
 
@@ -116,8 +116,8 @@ The recall commands read the git-ingester's queries at `https://git.tonbo.dev/ap
 ## Handoff
 
 ```console
-yield [--session <id>] [--task <text>] [--recover | --new]
-yield take <link> [--into <directory>]
+yield [--session <id>] [--task <text>] [--to <who>] [--recover | --new]
+yield take <link> [--into <directory>] [--account <organization>]
 yield done "<result>"
 yield need-human "<why>"
 yield pull <session-or-link> [--patch]
@@ -125,12 +125,13 @@ yield show <link>
 yield renew <link> [--result]
 ```
 
-Handoff is personal in this release: you hand a session to yourself on another computer under the same account.
+A handoff is in the Project of the folder it is made in. In a personal Project you hand a session to yourself on another computer or harness. In a shared team Project (`yield connect --account <organization>`) you hand it to any member, or with `--to <name>` to one member; `--to claude-code` or `--to codex` is you on that harness. A member's login of the organization is what makes and takes team handoffs, so the teammate needs one on their computer (`yield login --account <organization>`). Handing off to a device is not available in this release.
 
-- Bare `yield` hands off the current session of this Project (`--session` when more than one is live). The daemon captures the session up to now and publishes a snapshot of the worktree, gitd pins that exact commit, and the command prints a `/y/<id>` link. After a lost response, `--recover` retries the same snapshot and `--new` takes a fresh one.
-- `take` restores the pinned snapshot into a new `tonbo/h/<short id>` worktree on top of a base commit you already have, and prints the session's recent turns. The source worktree is never touched.
-- Inside that worktree, `done` pushes and pins the result and records the handoff done; `need-human` records that it is waiting on you.
-- `pull` fetches the latest unpulled result of a session (or a handoff link) onto a branch, or with `--patch` into a patch file, without changing your worktree.
+- Bare `yield` hands off the current session of this Project (`--session` when more than one is live). The daemon captures the session up to now and publishes a snapshot of the worktree, gitd pins that exact commit, and the command prints a `/y/<id>` link and who it is for. After a lost response, `--recover` retries the same snapshot and `--new` takes a fresh one. A session that started before its folder was shared stays personal and cannot be handed to the team.
+- `take` restores the pinned snapshot into a new `tonbo/h/<short id>` worktree on top of a base commit you already have, and prints the task, the session's files and its recent turns (read from the team's store for a team handoff). The source worktree is never touched. Without `--account` it tries your personal account and then each organization this computer is logged in to; a handoff you may not take is not found.
+- Inside that worktree, `done` pushes and pins the result and records the handoff done; `need-human` records that it is waiting on you. Both use the login of the account the handoff is in.
+- `pull` fetches the latest unpulled result of a session (or a handoff link) onto a branch, or with `--patch` into a patch file, without changing your worktree. The author pulls a teammate's result the same way.
+- `show` prints a handoff's state, author, who it is for and who took it, and its captured context, without taking it. Any member can show a team handoff.
 
 ## The Tonbo skill