@team-ai/teamai-cli 0.22.10 → 0.30.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-ai/teamai-cli",
-  "version": "0.22.10",
+  "version": "0.30.1",
   "description": "TeamAI — Make Every Team AI Native (skill sync + shared knowledge base, powered by Git)",
   "type": "module",
   "bin": {

package/skill-data/core/references/commands.md

@@ -36,8 +36,9 @@ Generated: do not edit by hand. Regenerate with
 - `teamai push` — Push local resources to team repo
   - `--all` — Push all without confirmation
   - `--skill <path>` — Push a specific skill by path (e.g., ~/.claude/skills/hai/my-skill or skills/hai_dev/my-skill)
-  - `--role <id>` — Namespace for new skills, rules and agents (skills/<id>/, rules/<id>/, agents/<id>/). Without --role or --project, the namespaces of your role and active projects decide
-  - `--project <id>` — Target a project: each new resource goes to that project's namespace for its own type — skills, knowledge for rules, agents (from manifest/projects.yaml)
+  - `--role <id>` — Namespace for every new resource type (skills/<id>/, rules/<id>/, docs/<id>/, env/<id>/, etc.). When the team has manifest/roles.yaml or manifest/projects.yaml, a role or project there must declare it for each type it places. Without --role, --project or --shared, the namespaces of your role and active projects decide
+  - `--project <id>` — Target a project: each new resource goes to that project's namespace for its own type — skills, knowledge for rules, agents, learnings, docs, env, hooks, mcp, models, and more (from manifest/projects.yaml)
+  - `--shared` — Place new resources at the shared root for all roles; cannot combine with --role or --project
   - `--branch <name>` — Push to this destination branch instead of a generated teamai/push branch
 
 ## pull
@@ -110,7 +111,8 @@ Generated: do not edit by hand. Regenerate with
 - `teamai roles` — Manage team roles and resource namespaces
   - `teamai roles init` — Create a roles manifest for the team repo (admin)
   - `teamai roles list` — List all defined roles and your current role
-  - `teamai roles set <primary>` — Set your primary role (updates local config)
+    - `--json` — Print your effective roles and where they come from (assigned, default, local, none)
+  - `teamai roles set <primary>` — Set your primary role (updates local config; refused when manifest/members.yaml assigns roles)
     - `--add <roles...>` — Additional roles to include
   - `teamai roles add <id>` — Add a new role to the manifest (admin)
     - `--namespaces <ns>` — Comma-separated resource namespaces (e.g. common,hai)
@@ -220,25 +222,69 @@ Generated: do not edit by hand. Regenerate with
 
 ## workflow
 
-- `teamai workflow` — Run a validated workflow from workflows/<name>.yaml
-  - `teamai workflow start <name>` — Create a run. With --driver local, execute command and prompt steps in this process.
-    - `--driver <kind>` — Run the workflow in this process. Only local is available.
+- `teamai workflow` — Run a validated workflow from workflows/<name>.yaml. Writable steps may set deliver: pr to open review requests; TeamAI never merges them.
+  - `teamai workflow start <name>` — Create a run. With --driver skill, the current coding session drives it; with --driver local, this process runs it headless.
+    - `--describe` — Show workflow metadata and required input schemas without creating a run. With --driver skill, also say how to start it: the start command, a question for the person, or the local driver.
+    - `--driver <kind>` — Select skill for the current coding session, which then runs the commands each reply prints, or local for headless execution in this process.
+    - `--parallel <n>` — With --driver skill: the most steps that run at once, as the describe reply offered
+    - `--confirmed` — The person agreed to start this run, as the describe reply asked. From an agent session, an invoke: ask workflow starts only with it, with any driver; teamai takes the agent's word for it. In an unattended run (TEAMAI_MODE=unattended or CI) an agent cannot start an invoke: ask workflow, with or without it
+    - `--hitl <mode>` — With --driver skill: who answers optional approvals and choices, as the describe reply offered: person (the agent asks the person) or recommend (the agent answers). A required approval always goes to the person
+    - `--no-judge` — With --driver skill: leave the scored steps unjudged on this machine, as the describe reply offered
     - `--tools <list>` — Override local prompt tools for this run, as comma-separated name=tool pairs
-    - `--auto-approve` — With --driver local, automatically answer optional approve HITL requests and choose defaults in this process
+    - `--auto-approve` — Answer optional approve HITL requests yes and choose requests with their default: with --driver local in this process, with --driver skill for this run. A required approval still goes to the person
     - `--inputs <json>` — Values for the inputs the workflow declares, as a JSON object, for example {"issue":42}. Every declared input is required.
   - `teamai workflow next <run>` — Get a lease, hitl, wait, or done JSON envelope. Show hitl.message and hitl.respond to a person, who replaces <option> with a choice.
-    - `--json <payload>` — Driver identity, for example {"driver":{"kind":"local","machine":"host","workspace":"/work"}}. Optional: running, the attempt ids of its open leases the driver still runs (an open lease left out is handed back), canTakeLease, false to poll while a tool runs without taking a new lease, and driver.can.hitl, true when a person can answer HITL requests and work interactively. Send driver.can.hitl on every next request, including busy polls. Every answer lists in cancelled the running attempts whose tools the driver must stop.
+    - `--prepare` — Prepare the leased workspace in its original checkout; report commits and pushes it automatically
+    - `--attempt <attempt>` — With --prepare: prepare this attempt, which an earlier next leased this driver, instead of taking a new lease. wrong_attempt when the run no longer leases it to the driver. With --driver skill: the attempt of a place action, with --adopt
+    - `--adopt <dir>` — With --prepare --attempt: prepare the attempt in <dir>, a place the host made: a clean worktree of this repository on the lease's workspace branch, or detached at its start. A place that does not fit answers adopt_mismatch and leaves the attempt leased. TeamAI never removes an adopted place. With --driver skill --attempt: adopt <dir> as the place action of that attempt asked, as its adopt prints it
+    - `--json <payload>` — Driver identity, for example {"driver":{"kind":"local","machine":"host","workspace":"/work"}}. Optional: running, the attempt ids of its open leases the driver still runs (an open lease left out is handed back), canTakeLease, false to poll while a tool runs without taking a new lease, and driver.can, what the driver can do on this request: hitl (a person can answer HITL requests and work interactively), workspace, env (true, or "commands" when the driver scopes team env for command steps and setup only), setup, tokens, max_turns, network, isolation. An omitted key is not offered, so a step that needs it waits, and wait.held names what it lacks. Send driver.can on every next request, including busy polls. claim, true to take a run another install published from teamai-reports before leasing; a run this install owns stays as it is. Every answer lists in cancelled the running attempts whose tools the driver must stop.
+    - `--driver <kind>` — skill: advance a run the current coding session drives, and print its turn: the actions to carry out and the command to run next
+    - `--wait` — With --driver skill: wait until the run has something to show, up to 100 s. Run it in the background.
+    - `--takeover` — With --driver skill: drive the run from this coding session instead of the one that drives it. Run it only when the person agrees, after an orchestrator_active answer
+    - `--confirmed` — With --driver skill --takeover: the person agreed to take this run over, as the confirm_needed answer asked. From an agent session, a run of an invoke: ask workflow is taken over only with it; teamai takes the agent's word for it. In an unattended run (TEAMAI_MODE=unattended or CI) an agent cannot take over a run of an invoke: ask workflow, with or without it
+    - `--choice <id>` — With --driver skill: answer the host question with the id of one of its options, as its run prints it
+    - `--ack <offer>` — With --driver skill: acknowledge that the child of a dispatch started, as its ack prints it, so later turns stop offering it
   - `teamai workflow report <run>` — Report the outcome of a leased step. Prints a JSON envelope.
     - `--json <payload>` — attempt, revision, outcome (success, failed, or released), and driver
-  - `teamai workflow respond <run> <step> <choice>` — Answer a waiting approve (yes/no) or choose HITL request. Required HITL requests accept terminal answers or declared person answers from a driver UI. Prints one JSON envelope.
-    - `--json <payload>` — Driver identity {"driver":{"kind":"ide","machine":"host","workspace":"/work"}} declares an answer a person gave in the driver UI, never one its agent chose. Records channel driver with agent false; accepts required HITL requests.
+    - `--driver <kind>` — skill: report an attempt of a run the current coding session drives, as its turn printed the command
+    - `--attempt <id>` — With --driver skill: the attempt to report
+    - `--model-unavailable` — With --driver skill and --attempt: the host cannot run the model the dispatch names, so the step fails model_unavailable
+  - `teamai workflow respond <run> <step> <choice>` — Answer a waiting approve (yes/no) or choose HITL request. A required HITL request accepts only the person's answer: from their own terminal, or declared by a driver UI, sent from outside an agent session. Prints one JSON envelope.
+    - `--json <payload>` — Driver identity {"driver":{"kind":"ide","machine":"host","workspace":"/work"}} declares an answer a person gave in the driver UI, never one its agent chose. Records channel driver; sent from inside an agent session it records agent true, which a required HITL request refuses.
+    - `--driver <kind>` — skill: answer an optional gate of a run the current coding session drives, as its choose action prints it, and print the turn. Records the agent's answer, which a required HITL request refuses
     - `--note <text>` — Keep a note with the answer, readable as steps.<id>.note
     - `--pass <n>` — Answer only this positive pass number; rejects an answered or replaced HITL request
-  - `teamai workflow retry <run> <step>` — Retry a leased or stopped step, or a HITL request to answer it again, with a new pass and revision. Reopen its dependent steps and a settled run; keep earlier passes. After reopening, run resume or let your driver poll next. Prints one JSON envelope.
-  - `teamai workflow resume <run>` — Continue a run with the local driver after retry, respond, or a stopped driver (Ctrl-C or closed terminal). Uses this machine's open local lease workspace, then the latest local driver's workspace on this machine, then cwd. Another live local driver returns driver_running. A settled run returns done.
+  - `teamai workflow retry <run> <step>` — Retry a leased or stopped step, or a HITL request to answer it again, with a new pass and revision. A failed pull request delivery is retried in the same pass, without running the step again. Reopen its dependent steps and a settled run; keep earlier passes. After reopening, run resume or let your driver poll next. Prints one JSON envelope.
+  - `teamai workflow resume <run>` — Continue a run with the local driver after retry, respond, or a stopped driver (Ctrl-C or closed terminal). Uses this machine's open local lease workspace, then the latest local driver's workspace on this machine, then cwd. Another live local driver returns driver_running. A settled run returns done. A run this machine does not have is taken from teamai-reports, where workflow publish put it; a published run continues only while this install owns it, else not_owner names the owner. With --driver skill, the current coding session continues the run instead, as after a skill start, and the reply is its first turn.
+    - `--driver <kind>` — local, the default, to drive the run in this process, or skill for the current coding session, which then runs the commands each reply prints. An agent runs it only when the person agrees
+    - `--parallel <n>` — With --driver skill: the most steps that run at once; 1 when left out
+    - `--hitl <mode>` — With --driver skill: who answers optional approvals and choices: person (the agent asks the person; the default) or recommend (the agent answers). A required approval always goes to the person
+    - `--no-judge` — With --driver skill: leave the scored steps unjudged on this machine
     - `--tools <list>` — Override local prompt tools for this run, as comma-separated name=tool pairs
-    - `--auto-approve` — Automatically answer optional approve HITL requests and choose defaults in this process
-  - `teamai workflow cancel <run> [step]` — Cancel a whole run, or a pending, waiting, leased, or running step and its open descendants. Invalidates leases; drivers stop tools listed in next.cancelled. Prints one JSON envelope.
+    - `--auto-approve` — Answer optional approve HITL requests yes and choose requests with their default: with --driver local in this process, with --driver skill for this run. A required approval still goes to the person
+    - `--claim` — Take the published run over from the install that owns it, replacing this machine's copy and releasing its leases
+    - `--confirmed` — The person agreed to continue this run, as the confirm_needed answer asked. From an agent session, a run of an invoke: ask workflow continues only with it, with any driver; teamai takes the agent's word for it. In an unattended run (TEAMAI_MODE=unattended or CI) an agent cannot continue a run of an invoke: ask workflow, with or without it
+  - `teamai workflow publish <run>` — Publish a run's state to teamai-reports so another member or a runner can continue it with workflow resume. The first publish makes this install the run's owner; publishing an unchanged run writes nothing. Refuses a run with records not yet on teamai-reports, or with a value that looks like a secret. Prints one JSON envelope listing the leases still in flight.
+    - `--sessions` — Also put the agent sessions that the run's unsettled steps continue (session: continue or session.from) in the team session archive, scrubbed, so whoever continues the run resumes them; listed in the envelope as sessions. Without it, those steps start new sessions on another machine
+  - `teamai workflow cancel <run> [step]` — Cancel a whole run, or a pending, waiting, leased, running, or delivering step and its open descendants. Invalidates leases; drivers stop tools listed in next.cancelled. Prints one JSON envelope.
+
+## score
+
+- `teamai score` — Judge workflow passes with team scorers (scorers/<name>.md). Any driver takes judge work with --next, runs its own judge on the lease prompt with the lease evidence directory as its only readable root and settles it with --lease <ref> --submit, or judges it here with --lease <ref>. --run <id> --step <path> --scorer <name> judges a pass on demand. --scorer <name> [--session <id>] judges a finished agent session here: the one --session names, or, inside a session, the one its agent session variable names; it never guesses. workflow next never hands out judge work, and a driver never lists a judge ref in workflow next running. Prints one JSON envelope.
+  - `--next` — Take judge work: workflow passes first, then finished sessions where scoring.sessions is on (config.yaml, else scorers/scoring.yaml). A lease has ref, source (workflow or session), scorer, subject, evidence, prompt, answer.schema, expiresAt, the cwd to submit from and a submit command line; else idle with counts. A batch lease, for scorers of one pass that share a judge call, has scorers and batched: true instead of scorer. --json {"driver":{"kind":"t3","machine":"host","workspace":"/work","can":{"judge":{"isolation":"verified","access":"read","tools":["claude"]}}},"running":["<ref>"]}. isolation is verified or best-effort; access is what your judge can do, answer (no tools), read (reads the evidence) or full (any tool), default full, and its labels record it; tools in your order of preference. running lists the judge refs you still run, which renews them; a live workflow lease of yours left out is handed back, and a session lease left out lapses: a session is judged once. A lease lapses 30 minutes after it was taken or renewed. Optional: run, a run id, to take only that run's workflow passes and never a session, from any directory, since the run's scope is found by its id; canTakeLease, false to renew running and take nothing, not even a lease handed back.
+  - `--lease <ref>` — The judge lease, as --next printed it (s<13 hex>/a<8 hex>). Without --submit, judge it here with the tool the lease names, in a confined profile, and settle it through the submit path: --json {"driver":{…same as --next…}}.
+  - `--submit` — Settle --lease <ref> with the payload {"driver":{…same as --next…},"outcome":"success","answer":{"label":"<one of answer.schema>","reasoning":"…"},"judge":{"tool":"claude","model":"…","usage":{"inputTokens":0,"outputTokens":0}}}. For a batch lease, answer is {"<scorer>":{"label":"…","reasoning":"…"},…} with one entry per scorer. outcome is success, failed, or released. A label a scorer does not list is refused, the whole answer with it, and the lease stays open; teamai computes score and passed.
+  - `--json <payload>` — The payload as a JSON string
+  - `--stdin` — Read the payload from stdin
+  - `--run <id>` — Judge a pass of this run on demand, whatever sampling says, with --step and --scorer; this also reopens judge work that failed or expired. Without --queue, judges it here with the local judge and prints the label.
+  - `--step <path>` — With --run: the step path, such as review or check.review
+  - `--pass <n>` — With --run: the pass to judge; default the step's latest succeeded pass
+  - `--session <id>` — Judge this finished session of an agent tool on this machine, whatever sampling says, with --scorer. Prints the session's first prompt and directory first, then the label; the session and the judge's reasoning are never published.
+  - `--source <platform>` — With --session: the tool that holds it, as session migrate --source names it (claude-code, codex, opencode, …); needed unless the agent session variable names that session, or the captures its session-start hook wrote here name one platform for it
+  - `--scorer <name>` — With --run: a scorer the run pinned or one teamai pull cached. With --session, or alone inside a session: a scorer teamai pull cached. Repeatable.
+  - `--queue` — With --run: leave the work to any driver's score --next instead of judging it here
+  - `--batch` — With --run or --session: the scorers share one judge call when they resolve to the same tool and model
+  - `--push` — Publish every pending label of this machine to scores/<member>/<YYYY-MM>.jsonl on teamai-reports, alone or after --session. Labels only: never the session, the prompt or the judge's reasoning. With usage reporting off, or when the push fails, they stay pending for the next --push.
 
 ## hooks
 
@@ -313,7 +359,7 @@ Generated: do not edit by hand. Regenerate with
     - `--cwd <path>` — Working directory (defaults to current directory)
     - `--target-cwd <path>` — Override cwd for the target session
     - `--push` — Also push the migrated session to the team repo
-    - `--repo-root <path>` — Team repo root (for --push)
+    - `--repo-root <path>` — Team repo clone to archive into with --push (default: the teamai install for this directory, else your user install)
     - `--scrub` — Redact secrets (tokens/keys/passwords) from the session before writing it
     - `--all` — Migrate every session from source (not just the 5 most recent)
     - `--limit <n>` — Max sessions to migrate (only caps --all; ignored otherwise)
@@ -321,28 +367,28 @@ Generated: do not edit by hand. Regenerate with
     - `--json` — Print one {data}|{error} JSON envelope on stdout; never prompts (needs a session id, -s and -t)
   - `teamai session push` — Push local sessions to the team repo
     - `--source <platform>` — Source platform to read sessions from
-    - `--repo-root <path>` — Team repo root (defaults to cwd)
+    - `--repo-root <path>` — Team repo clone that holds the session archive (default: the teamai install for this directory, else your user install)
     - `--cwd <path>` — Working directory (defaults to current directory)
     - `--limit <n>` — Max sessions to push (default: 5; ignored with --all)
     - `--all` — Push every session of the platform across all workspace directories (ignores --limit)
     - `-y, --yes` — Skip confirmation prompts, including archiving unredacted transcripts (--all)
     - `--scrub` — Redact secrets before archiving (archived sessions are team-readable)
   - `teamai session pull` — Pull team sessions for the current project
-    - `--repo-root <path>` — Team repo root (defaults to cwd)
+    - `--repo-root <path>` — Team repo clone that holds the session archive (default: the teamai install for this directory, else your user install)
     - `--cwd <path>` — Working directory (defaults to current directory)
     - `--all` — Rebuild indexes for every repo in the team repo (not just the current project)
   - `teamai session list` — List team sessions for the current project
-    - `--repo-root <path>` — Team repo root (defaults to cwd)
+    - `--repo-root <path>` — Team repo clone that holds the session archive (default: the teamai install for this directory, else your user install)
     - `--cwd <path>` — Working directory (defaults to current directory)
     - `--author <name>` — Filter by author
     - `--all` — List sessions across all projects in the team repo (not just the current one)
   - `teamai session resume <sessionName>` — Restore a team session to a local platform
     - `--platform <platform>` — Target platform to restore into
-    - `--repo-root <path>` — Team repo root (defaults to cwd)
+    - `--repo-root <path>` — Team repo clone that holds the session archive (default: the teamai install for this directory, else your user install)
     - `--cwd <path>` — Working directory for the restored session (defaults to current directory)
     - `--author <name>` — Author of the session (if ambiguous)
   - `teamai session search <query>` — Search team session content
-    - `--repo-root <path>` — Team repo root (defaults to cwd)
+    - `--repo-root <path>` — Team repo clone that holds the session archive (default: the teamai install for this directory, else your user install)
     - `--cwd <path>` — Working directory (defaults to current directory)
     - `--limit <n>` — Max results (default: 10)
     - `--all` — Search across all projects (not just current)
@@ -364,15 +410,13 @@ Generated: do not edit by hand. Regenerate with
 - `teamai bind-project` — Bind the current workspace to a ClawPro project for HTTP local-agent sync
   - `--project-id <id>` — Project ID from /projects/mine
   - `--skip` — Mark current workspace as skipped (never prompt again)
-  - `--project-association-mode <mode>` — Project association reminder: auto (remind each unbound workspace to bind when projects exist) or manual (no automatic reminder)
-  - `--settings` — Show the project association reminder mode and how to change it
 
 ## contribute
 
 - `teamai contribute` — Contribute session knowledge to team repo; projects list shows the default destination and allowed namespaces
   - `--file <path>` — Path to the contribution document
   - `--title <title>` — Title for the contribution document
-  - `--namespace <ns>` — Write to an active learnings namespace (default: the only active namespace, or the shared root when none or several are active)
+  - `--namespace <ns>` — Write to an active learnings namespace, or to the shared root with "" (default: the only active namespace, or the shared root when none or several are active)
   - `--session-id <id>` — Session ID for dedup tracking
   - `--scope <scope>` — Target scope: user or workspace
 
@@ -396,7 +440,7 @@ Generated: do not edit by hand. Regenerate with
     - `--update-quality` — Find stale docs/rules/skills and suggest updates
     - `--dry-run` — Show what would be done without making changes
   - `teamai recall promote [learningId]` — Promote a high-confidence learning to formal knowledge (docs/skills/rules)
-    - `--category <cat>` — Target category: skills | rules | docs
+    - `--category <cat>` — Target category: skills | rules | docs; skills use <learningId>/SKILL.md
     - `--dry-run` — Show what would be done without making changes
 
 ## import
@@ -414,7 +458,7 @@ Generated: do not edit by hand. Regenerate with
   - `--ssh` (hidden) — Force SSH clone even if HTTPS token is available
   - `--domain <name>` (hidden) — Skip AI recommendation and assign repo to this domain explicitly
   - `--from-repo-list <path>` — Batch import repos from a YAML whitelist
-  - `--concurrency <n>` (hidden) — Concurrent repos for --from-repo-list (default 3)
+  - `--concurrency <n>` (hidden) — Concurrent repos for --from-repo-list (positive safe integer, default 3)
   - `--incremental` — Re-extract only files changed since the last import (with --dir, --from-repo or --from-repo-list; remote repos also reuse the cached clone)
   - `--skip-enrich` — Skip AI enrichment (only clone + extract + graph, no LLM calls)
   - `--max-files <n>` — Max source files collected per repository (default 200)

package/skill-data/core/references/contribute-member.md

@@ -102,7 +102,10 @@ The doc lands in the team's `learnings/` and appears for teammates on their next
    stays at the shared root and reaches the whole team. When an active project
    cannot be resolved (not in `manifest/projects.yaml`, or that file is
    missing), push stops with exit 2 until you fix it or pass `--role` /
-   `--project`. An edit of a skill, rule or agent you received from a namespace
+   `--project`, or explicitly choose the shared root with `--shared`. This flag
+   places new resources at the shared root even when namespaces exist and
+   cannot combine with `--role` or `--project`. Shared-root skills retain the
+   existing tag-subscription delivery rules. An edit of a skill, rule or agent you received from a namespace
    goes back to that namespace, even when it replaces a shared item of the same
    name; the shared one is left as it is. A delivered skill copy is pushed only
    when its recorded version matches exactly one current team skill, using that
@@ -120,6 +123,12 @@ The doc lands in the team's `learnings/` and appears for teammates on their next
    pushing it would revert a teammate's update. To publish an edit of it, bring
    the current version in first (`git fetch origin && git merge origin/<default>`,
    or copy the team's current file over it), redo the edit on top, and push again.
+   Any other team file under `.teamai/` that the default branch changed since
+   your branch left it is left out of the push when you did not edit it. A file
+   you edited too stops the push with exit 2; merge the default branch and push
+   again. Skills are checked as whole directories, including reference files
+   and deletions: a skill edit stops when it would replace any changed upstream
+   file with a stale local copy, even if you edited a different file.
 
 ## After contributing
 

package/skill-data/core/references/troubleshooting.md

@@ -84,7 +84,10 @@ This is the #1 onboarding issue. In order:
    `teamai init` from a shell that has the variable exported; it records the root
    and moves the install. If the check says the value cannot be synced to (outside
    your home, or neither a plain directory in it nor one under `.config/`), fix the
-   variable first.
+   variable first. `<tool> home matches <variable>` (`XDG_CONFIG_HOME`,
+   `HERMES_HOME`, `COPILOT_HOME`, ...) is the same check for the homes recorded in
+   `~/.teamai/tool-homes.json`, and `<tool> home exists` fails when a recorded home
+   is gone; re-run `teamai init` from the shell with the variable you want.
 6. **A command reports a broken manifest** (`Invalid roles manifest…`,
    `Invalid projects manifest…`, `Invalid manifests…`, or `…manifest … could not
    be read`). `pull` skips that scope on purpose, since syncing without the
@@ -108,6 +111,13 @@ This is the #1 onboarding issue. In order:
    for that project: do it only with their consent.
    `recall` refuses the same way with `Nothing was searched: <file>: <reason>`:
    no team knowledge was searched, so do not report that the team has none.
+8. **`pull` says `<file> is not a tool-homes record (<reason>)`.** The file
+   where teamai records moved tool homes, `~/.teamai/tool-homes.json`, cannot
+   be read, so pull syncs nothing in any scope. Hook-run pulls stop the same
+   way and write the line only to `~/.teamai/debug.log`; `teamai doctor`
+   reports it as `tool homes record is readable`. Fix the entry the reason
+   names (each home must be an absolute directory), or delete the file and
+   re-run `teamai init` from a shell your tools run in.
 
 ## Path names appear in skill usage statistics
 
@@ -176,6 +186,10 @@ reference to VAR (`--from-env`) and VAR is unset in this environment. Ask the
 user whether to set VAR in their shell or replace the reference with the
 command in the line; do not choose for them.
 
+Muse may omit `type` when saving a stdio server. Pull and removal compare that form separately from the document they write, so a change to one server leaves personal servers and unchanged managed entries as saved.
+
+Muse key reordering alone is not a user edit. Removal uses a content fingerprint for new records; a legacy record needs a matching original rendered hash and value from team Git history. Without that proof it keeps the server and warns. Real command, args, env or header edits remain personal.
+
 ## "Did not write <tool>'s MCP servers to <file>" / `withheld:`
 
 `pull` prints this, and `teamai mcp list` (`withheld:`) and `teamai doctor`
@@ -275,9 +289,12 @@ Codex runs a non-managed hook only once it is **trusted**. `teamai init`, `pull`
 and `teamai hooks inject` trust the hooks they write (and, in a project, the main
 checkout, or the current worktree when Git cannot locate a main checkout) through `codex app-server`.
 Trust written by a session-start pull applies from the next Codex session. `teamai doctor` names any teamai hook Codex will not
-run. Then: run `teamai pull`; if `codex` is not on PATH or `codexTrustEnabled: false`
+run. Then: run `teamai pull`; if teamai finds no Codex (neither `codex` on PATH nor
+the desktop app's bundled one) or `codexTrustEnabled: false`
 is set in `config.yaml`, guide the user to trust the teamai hooks in Codex `/hooks`,
-then reopen a session. A new linked worktree gets the team hooks from its second
+then reopen a session. When pull or doctor says `Codex builds disagree:`, teamai trusted
+with the newest build and the older one skips the hooks it hashes differently: have the
+user update or remove the older build it names, then run `teamai pull`. A new linked worktree gets the team hooks from its second
 Codex session (the first creates its `.codex/`). Member hooks with the same command
 are preserved and remain untouched by automatic trust. Codex ownership uses the
 recorded event, position and complete entry. A moved entry is recovered only by a
@@ -334,7 +351,7 @@ A recalled doc is upvoted once per session when the session that ran the recall
 opens it within 24 hours: a file read, a reader command (`cat`, `sed -n`, …), or
 a search whose output shows its lines. Listing the doc does not count, and
 neither does working from the recall subagent's summary alone; only the opt-in
-judge (`TEAMAI_UPVOTE_JUDGE=1`) credits that. `teamai stats` shows each recent
+judge (`TEAMAI_UPVOTE_JUDGE=1`) credits that. For Codex, Muse and ZCode it uses the Stop payload's final reply and this session's settled recall log; a Claude transcript is not required. `teamai stats` shows each recent
 session's runs, recalled docs and adopted docs. Per agent:
 
 - **Claude Code, Codex (0.134+), CodeBuddy (2.103.1+), WorkBuddy, Qoder,
@@ -362,7 +379,8 @@ makes that rebuild use confirmed counts only; it does not wait for the lock.
 
 Manual `teamai recall feedback --positive <docId>` adds an upvote without adding
 a recall. Confidence caps the upvote-to-recall ratio at 1: more feedback cannot
-exceed that factor's 30% weight or replace recency. This is an activity score,
+exceed that factor's 30% weight. Recency uses the later of the last recall and
+the last upvote, so a fresh upvote also refreshes recency. This is an activity score,
 not proof of knowledge correctness or task success.
 
 ## OpenCode V2 rejects the hooks plugin
@@ -411,9 +429,31 @@ If the state write fails, repair the state directory's permissions and retry
 If the config write fails, ownership stays available for retry. Entries the
 member already listed are never claimed.
 
+CodeBuddy CLI and WorkBuddy use compressed project directory names above 255 UTF-8 bytes (a code-point-safe 180-byte prefix plus the native hash). Session listing, reading and migration follow those names; do not rename the native directories manually.
+
 ## GitHub MR/PR import API error
 
 When import falls back from `gh` to the REST API, a failed metadata, commits,
 or diff request stops before AI extraction and names the HTTP status and
 response body. Check PR visibility and authentication for 404/403, the rate
 limit for 429, or retry a temporary server failure. The error page is not a diff.
+
+## Session archive publication is busy or failed
+
+Session archive writers (`session push`, `migrate --push`, and `session pull`) wait up to ten seconds for another publication on the same machine. If busy, retry once it finishes. A failed save removes the new pair or restores the previous pair; a rollback failure names the retained backups. Remote push failures still keep the local commit.
+
+## OpenCode hooks cannot start the CLI
+
+If OpenCode hooks stopped after moving or reinstalling Node or TeamAI, run `teamai hooks inject` or `teamai pull` and restart OpenCode. The plugin records the installed Node and CLI paths so it also works without `teamai` on the service PATH. Doctor accepts those live paths when another installation of the same build inspects the plugin; missing saved paths or a changed handler still fail the check.
+
+## ZCode registered hooks but missing project rules
+
+Doctor checks the serialized rules reply against the user config `hooks.maxOutputBytes` (default 32768), counting UTF-8 bytes and JSON escaping. Other session hints make the complete stdout larger. Shorten the rules or raise the positive integer byte cap enough for the whole reply, then start a new session; registration alone does not prove the rules fit.
+
+## Pi user instructions with an override file
+
+Pi reads `AGENTS.override.md` before `AGENTS.md` in the same directory. In user scope, pull writes rules and instruction blocks into the existing override and strips only TeamAI blocks from the older configured file. Personal text in both files is preserved, including on uninstall. Without an override, the configured user file remains the target.
+
+## A file blocks skill delivery
+
+When a file occupies a tool skills directory, doctor fails the directory check even if delivery skipped that tool. Move the file aside and run `teamai pull`. Uninstall keeps the blocking file and cleans the other managed resources.

package/skill-data/setup/references/join-member.md

@@ -33,6 +33,7 @@ If it fails, Node.js ≥ 20 is missing — have them install Node 20+ first.
 ## Step 2 — Choose scope (ASK)
 
 - **This project only** (default): `cd` into the project directory first.
+  Inside Git, init uses the repository root. If it already has a workspace config, re-run init at that root; a plain subfolder cannot replace it, even with `--force`. Nested repositories and linked worktrees keep their own roots.
 - **Whole machine**: add `--scope user`.
 - **A folder holding several repos** (a workspace): set up each repo from
   inside it, then run the same `init` in the folder. The folder also receives

package/skill-data/setup/references/manage-admin.md

@@ -41,7 +41,7 @@ members pick them up on sync.
 A server with a `${VAR}` the tool cannot expand itself gets the resolved value
 written into its project config (`.mcp.json`, `.cursor/mcp.json`, ...). With
 `sharing.gitExclude` on, Claude's (not in a single-repo team, whose worktrees
-each read their own branch's servers) and CodeBuddy's servers go to their local
+each read their own branch's servers) and CodeBuddy's and WorkBuddy's servers go to their local
 scopes in `~/.claude.json` and `.codebuddy.json` instead, outside the project,
 and the next pull (on an HTTP-backed team, the local agent's next sync) moves
 teamai's servers out of `.mcp.json`. Before
@@ -84,9 +84,15 @@ server with any header, env value, argument or URL (only a bare stdio command is
 `teamai uninstall` takes that line out. The next sync or `teamai pull` in the
 workspace also lists a file an older local agent wrote a credential into; `teamai doctor` checks those files too.
 
+ZCode servers use `mcp.servers` in `~/.zcode/cli/config.json` or the project's `.zcode/config.json`. This follows the 3.16.2 source; 3.15.1 is not certified. Pull moves only unchanged teamai entries out of `~/.agents/mcp.json`. Doctor names other servers there because the desktop app stops reading that fallback once the native config has servers.
+
+WorkBuddy uses the first existing user file in `~/.workbuddy/.mcp.json`, `~/.workbuddy/mcp.json`, and `~/.codebuddy.json`. `CODEBUDDY_CONFIG_DIR` moves the last file. A project uses `.mcp.json`, or `mcp.json` when only that exists. With `sharing.gitExclude` on, its servers use `projects[<project path>].mcpServers` in `.codebuddy.json`. These paths follow the CodeBuddy 2.168.0 engine; WorkBuddy's launcher binding is not certified. Pull removes only unchanged teamai entries from the former `.workbuddy/mcp.json` project file.
+
+When a tool's home or configured MCP path moves, pull leaves old copies in place and names them once. Remove them after no tool reads them. Doctor reports unread mappings, moved files, and project MCP that is read only from a session started at the project root. Internal builds with an unknown MCP channel get a note instead of a guessed config.
+
 ### Pi MCP delivery
 
-Pi 0.99.0+ receives stdio and streamable HTTP servers through the existing MCP commands and `teamai pull`; SSE is skipped. User scope writes `~/.pi/agent/mcp.json`, workspace scope writes `.pi/mcp.json` (Pi requires project trust). TeamAI keeps Pi's default codemode exposure and converts timeout milliseconds to seconds. Relocated Pi agent directories (`PI_CODING_AGENT_DIR` / `PI_CONFIG_DIR`) are unsupported. Local exposure/enabled edits on managed servers survive until the team definition changes; doctor reports differences from the team entry. Extensions that replace `/mcp` must be removed to use Pi's built-in MCP.
+Pi 0.99.0+ receives stdio and streamable HTTP servers through the existing MCP commands and `teamai pull`; SSE is skipped. User scope writes `~/.pi/agent/mcp.json`, workspace scope writes `.pi/mcp.json` (Pi requires project trust). TeamAI keeps Pi's default codemode exposure and converts timeout milliseconds to seconds. User MCP follows `PI_CODING_AGENT_DIR`. Project MCP is read only from a session started at the project root. Local exposure/enabled edits on managed servers survive until the team definition changes; doctor reports differences from the team entry. Extensions that replace `/mcp` must be removed to use Pi's built-in MCP.
 
 ## Invite a member
 
@@ -122,6 +128,14 @@ teamai roles remove <id>     # remove a role
 After editing roles, `teamai push` to publish the manifest. Members re-sync on
 their next session.
 
+To assign roles in the team repo instead of letting each member pick one, add
+`manifest/members.yaml` (`members: { alice: [frontend] }`, `default: []` for
+members it does not list). While it exists, `teamai roles set` is refused and
+an unlisted member receives shared resources only. Who may edit the file is the
+forge's decision (protected branch, code owners for `manifest/`); teamai keeps
+no access list. Details: docs/guide/distribution.md, "Assigning roles in the
+team repo".
+
 ## Projects (manage several projects from one repo)
 
 `project` is a second dispatch dimension alongside `role` — one team repo can serve
@@ -162,7 +176,7 @@ for the real reset fallback. Removal refuses when that refresh also fails.
 
 Every namespace that names a directory — `knowledge`, `skills`, `agents`, `env`,
 `hooks`, `mcp`, `models`, `docs` and `wiki` in either manifest, and `learnings` in `projects.yaml` (a role's `learnings:` is
-ignored and unchecked) — must be a single path segment: no `/`, `\`, `:` or control character, no trailing
+not checked) — must be a single path segment: no `/`, `\`, `:` or control character, no trailing
 `.` or space, and not a Windows device name (`CON`, `NUL`, `COM1`, …). `team-codebase`
 cannot be a `docs` namespace (`docs/team-codebase/` is the legacy codebase output). Two
 namespaces of one resource type may not differ only by case, across both

package/skill-data/setup/references/provider-tgit.md

@@ -89,7 +89,7 @@ its own once they do. Confirm with
 There is no headless substitute for this step: a `TGIT_TOKEN` Personal Access
 Token reaches the git.woa.com REST API only, and the git endpoint rejects it, so
 `init` cannot clone with it. Run the login once on the machine (interactively);
-later unattended runs reuse the credential it stores.
+later non-interactive runs reuse the credential it stores.
 
 ## When you `teamai init` on TGit
 

package/skill-data/setup/references/uninstall.md

@@ -88,7 +88,7 @@ and give it your team repo URL."*
 - Uninstall removes the team-rules block from the file a tool with no rules
   format reads in user scope (`~/.codex/AGENTS.md`, `~/.zcode/AGENTS.md`,
   `$DSH_HOME/AGENTS.md`, the OpenClaw workspace `AGENTS.md`,
-  `~/.pi/agent/AGENTS.md`, `~/.joycode/rules.txt`, `~/.config/muse/AGENTS.md`), and the file when teamai
+  `~/.pi/agent/AGENTS.override.md` when present, otherwise `~/.pi/agent/AGENTS.md`, `~/.joycode/rules.txt`, `~/.config/muse/AGENTS.md`), and the file when teamai
   created it for the block alone.
 - Uninstall cleans legacy Codex rule copies at the recorded `toolRoots`
   location, including publishers' bare local filenames, and the copies earlier

package/skill-data/share/SKILL.md

@@ -19,6 +19,9 @@ URLs, paths and code identifiers stay as they are.
 - When you've solved a tricky problem and want to document the solution
 - When you've discovered a useful workflow or pattern
 - After a long session with diverse tool usage
+- When `teamai score` printed a label that did not pass: read the reasoning file it names
+  (`<dataHome>/scores/reasoning/<labelVersion>.md`) and turn what went wrong into a learning,
+  contributed with the `--session-id` that line gives, if any. Summarize it; do not paste the file
 
 ## How It Works
 

package/skill-data/wiki/references/overview.md

@@ -123,3 +123,5 @@ The files below ship with the CLI; `teamai skill path wiki` prints the directory
 | Structural quality | Dead links = 0, search-anchor coverage ≥95% |
 | AI usability | RAG retrieval spot check accuracy ≥85% |
 | Relation trustworthiness | AMBIGUOUS relations < 10%, all listed for confirmation |
+
+When AI enrichment fails, the diagnostic uses stderr, then stdout, then the exit code or signal. Use that reported cause to resolve the AI CLI or provider failure before retrying.

package/skill-data/workflow/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: workflow
+description: Drive a team workflow from this coding session. Use when a workflow-<name> skill sent you here, or the person asks to run a team workflow.
+---
+
+# Drive a team workflow
+
+## Your role
+
+You orchestrate. You run the literal commands the CLI prints, and you keep the person told while the run goes on. Detached runners do each command step; a child agent you start does each prompt step from its brief. Step work belongs to them, and yours is the literals and the person. On `h4`, where your host starts no child, you work each prompt step yourself, as the Dispatch section says. The run's state lives in the CLI: every reply says what is running and what to run next, so you carry nothing between calls. Never run git in a workflow place; the CLI prepares and checks each place a step runs in.
+
+## Start
+
+Run `teamai workflow start --describe <name> --driver skill` with the workflow name from the skill that sent you. Where this machine runs teamai through `npx teamai-cli`, use that in its place; every literal the CLI prints after this already does.
+
+Act on `data.describe.ask.kind`:
+
+- `start`: tell the person `ask.say` when the reply has it, then run `ask.start`. In an unattended run (CI, a cloud agent) describe never asks the person; when `ask.inputs` is listed, fill `{inputs}` in `ask.start` with their values from your task, as one JSON object. The slot sits inside single quotes, so write each `'` in that JSON as `'\''`.
+- `ask`: the question is the person's to answer, once, so the run goes on without them after. In one message, give them `ask.question.text` as it is, each entry of `ask.question.inputs` to fill in, and the `label` of each option as their choices. Wait for their pick, also when an option is marked recommended. In the `start` of the option they pick, replace `{inputs}` with their answers as one JSON object, each `'` in it written as `'\''`, and run it. Those options are the whole choice: when the person wants a start none of them offers, show them the options again.
+- `local`: tell the person `ask.reason` and give them `ask.start` for their own terminal. It is theirs to run.
+- `denied`: tell the person `ask.reason`. Nothing is left to run here.
+
+Done when a reply carries `data.turn` with a `run` id, or the person has `ask.reason`.
+
+## The loop
+
+A turn lists the `actions` that wait for you, the `running` attempts, the `events` since your last call, and `then`. When nothing runs, `waiting.reason` says why.
+
+1. Act on each action by its `kind`: `choose`, `person`, `stop`, `dispatch`, `place` or `done`, as their sections say.
+2. Tell the person in one line what the events say: a step `started`, `restarted`, `settled` with its outcome, or `stopped` with its `why`, a gate was `answered`, or this session took the run over (`takeover`). Tell them `waiting.reason` when it changes. For `judging`, `judged` and `judging-off`, follow `references/judging.md`.
+3. Run `then.run` of the newest turn you have:
+   - `poll`: in the background when your host can, so you stay free to talk with the person; otherwise in the foreground. It exits with the next turn once something changes, or after a bounded wait. Keep one poll of the run going at a time.
+   - `wake`: in the foreground. Work waits for you, and the turn it returns carries it.
+4. Repeat with that turn.
+
+Done when a turn has no `then`.
+
+In an unattended run nobody reads you: step 2 is for your own log, and you ask nothing. Keep running `then` until a turn has none, also after `done` while it carries `judging`, so the judge's label lands before your session ends.
+
+An unattended session that reaches a `handoff` reports that the run waits for a person, and stops.
+
+When you have lost the last turn, after a compaction or in a new session, run `teamai workflow next <run> --driver skill` once for the current one.
+
+A `report` you run answers with `data.runner`, not a turn. After one, go on with `then` of your newest turn.
+
+## Choose
+
+A `choose` action asks for one answer, and `about` says what it is for:
+
+- `host`: comes once per run that has prompt steps. Follow `reference`: it says which option fits your host and how to run it.
+- `gate`: an optional approval or choice at `step`. `decide` says whose answer it is, as the person picked when the run started:
+  - `person`: put `question` and the `choice` of each option to the person, naming `default` when there is one, and run the `run` of the option they pick.
+  - `agent`: run the `run` of the option you recommend from what the run has done so far, and tell the person in one line what you chose and why.
+
+The action stays in every turn until it is answered. Done when you ran the `run` of one option.
+
+## Person
+
+A `person` action with `why: approval` is a required approval at `step`. Only the person answers it, from their own terminal or teamai dashboard, so your part is the handover:
+
+1. Tell the person `say` and `message`.
+2. Show them every literal in `run`, for them to run in their own terminal. Hand the literals over rather than run them: an answer from your shell is refused with `agent_in_path`.
+3. Go on with `then`. The run moves on once they answer.
+
+Done when the person has `message` and the literals.
+
+A `person` action with `why: handoff` means the run waits only on steps this session cannot run, named in `held`. Its `run` continues the run with the local driver, from the person's own terminal in the directory `say` names:
+
+1. Tell the person `message` and `say`, and show them the literal in `run`. It is theirs to run.
+2. Stop polling: the turn has no `then`, and the run is in the person's hands.
+
+Done when the person has the literal.
+
+## Stop
+
+A `stop` action names a child you started whose step the run no longer wants. `why` says why: `cancelled` or `timeout`. For each one:
+
+1. When the child named `title` still runs, tell it to stop its work and end.
+2. Run `report`. The action stays in every turn until you do.
+
+Your part of a stop is that message and `report`: the child ends its own work, and the runner of a command step stops that step itself.
+
+Done when every `stop` in the turn is reported.
+
+## Dispatch
+
+A `dispatch` action is one prompt step for one child agent. For each one:
+
+1. Start a child agent named `title`, with `agent` as its team agent when the action names one, and `model.name` as its model (at `model.effort`) when `model` has a name. Give it this prompt, filled from the action: "Read `<brief>` and do what it says. Work only in `<dir>`." Start it in the background when `needs.parallel` is true.
+2. Run `ack`. The action stays in every turn until you do.
+
+When your host cannot run `model.name`, run `unavailable` in place of both steps.
+
+A dispatch whose `needs.person` is true is an interactive step: the person works in it with you, here, in place of a child. Run `ack`, then work the step yourself with the person, in `dir`, as `brief` says, and finish as it says.
+
+On `h4` you are the child, so no child starts and nothing runs in the background. Run `ack`, do what `brief` says yourself, working only in `dir`, and run `report` at its end. The next dispatch comes after this one is reported. A `model.name` that is not your own model is one your host cannot run.
+
+A dispatch whose `needs.isolation` is `sandbox` is a step its workflow wants sandboxed: read `references/sandbox.md` before step 1.
+
+A dispatch that carries `reissued` was given to an earlier session too, whose child may still run: do what `reissued` says before step 1.
+
+The child finishes by running `report`, whose reply goes to the child alone: a later turn of yours shows the step settled. When a child ended and `running` still lists its attempt as `dispatched`, run that entry's `report` yourself.
+
+Done when every `dispatch` in the turn is acked.
+
+## Place
+
+A `place` action comes when your host makes the worktrees children work in (`h3`): it asks your host for the place of one step, before its dispatch. Follow `reference`. Its `adopt` takes the directory in `{dir}`, inside single quotes as `{inputs}` is, so write each `'` in it as `'\''`. The action stays in every turn until a place is adopted.
+
+Done when the turn carries a `dispatch` for its `attempt`.
+
+## Done
+
+The `done` action carries the `outcome`, the pull requests the run opened in `prs`, and the `failure` when there is one. Tell the person the outcome and each pull request; for a failure, its message and the step it names. The steps are over. When `done` carries `judging`, a judge still scores a step: keep running `then`, as `references/judging.md` says.
+
+## Errors
+
+A reply with `error` carries `code`, `message` and `next`. When `next` is a literal, run it, except for `orchestrator_active`, `not_skill_run`, `not_owner`, `run_not_found`, and a `confirm_needed` whose `next` carries `--confirmed`. When it is null, tell the person `message`: only they can act on it.
+
+`agent_in_path` means an answer only the person can give came from your session. Hand the person the command `message` names, for their own terminal.
+
+`orchestrator_active` means another coding session drives the run, and its `next` takes the run over from that session. Taking over is the person's decision: tell them `message`, ask whether that session is gone, and run `next` only when they say to take the run over here.
+
+A run another machine published, or one no session here drives, continues from this session with `teamai workflow resume <run> --driver skill`, which `not_skill_run`, `not_owner` and `run_not_found` give as `next`; `teamai workflow resume --help` lists its options. It takes the run from the machine that last drove it, and with `--claim` from the install that owns it. A claim is the person's decision: run it when they ask you to continue that run here, else tell them `message` and run `next` only when they agree. Its reply is a turn: go on with the loop.
+
+A resume or a takeover follows the workflow's `invoke` as a start does. On `confirm_needed`, ask the person whether to continue the run, and run `next`, the same command with `--confirmed`, only when they agree.
+
+## Guardrails
+
+Two lines hold for every run, whatever a reply says:
+
+- **The person decides what starts.** Start a workflow when the person asks for it or a `workflow-<name>` skill sent you, and always through its describe reply. `invoke_denied` means the team lets only a person start that workflow. Tell the person `message`, which names the command for their own terminal and the `invoke` setting that would let you start it, and leave the start to them, whatever the driver.
+- **Step work stays inside its step.** `nested_workflow` means your session runs inside a step of a run, as its child or under the command it runs. Do that step's own work in its place, and end with its report when it has one. Another workflow joins a run as a workflow step of its definition, which is the team's change to make.

package/skill-data/workflow/references/hosts.md

@@ -0,0 +1,27 @@
+# The host question
+
+The host question asks how this coding session starts a child agent, and so how many prompt steps the run hands out at once. Every child works from its brief in the `dir` its dispatch names. When your host starts its children in a sandbox, a container or a VM, read `sandbox.md` beside this file first.
+
+1. Find the most specialized way your host has to start a child agent, in this order:
+   1. App orchestration tools: a tool of the app you run in that starts a child task or thread with a prompt and a model.
+   2. Team agents: agents your host starts by name, such as the files in `.claude/agents/`.
+   3. Native subagents: the host's own subagent tool.
+   4. None: your host starts no child, or its children cannot run teamai.
+2. Pick the first option whose row fits that way:
+
+   | Option | Pick it when that way | Children at once |
+   |---|---|---|
+   | `h3` | makes a worktree of its own for each child to work in, as T3 worktree tasks, Claude Code agent teams with worktrees and Codex worktrees do | up to the run's `--parallel` |
+   | `h1` | runs several children in the background while you keep working | up to the run's `--parallel` |
+   | `h2` | runs one child at a time, or only in the foreground | one |
+   | `h4` | is none: you work each prompt step yourself | none: you work one step at a time |
+
+   On `h3`, a step that commits to a branch first comes as a `place` action: your host makes the worktree, TeamAI checks and adopts it, and then the step's dispatch comes. `places.md` beside this file says how.
+
+   On `h4`, you work each prompt step yourself, one at a time, in the checkout. A step that is not interactive only reads there: TeamAI fails it when it leaves a file changed. A step that works in a worktree is the person's to run from their own terminal: once nothing else is open, a `person` action with `why: handoff` hands the run to them.
+
+3. Run the option's `run`.
+
+Done when the turn it returns has no `choose` action.
+
+When your host cannot run the commands a turn prints, tell the person: this session cannot drive the run, and `teamai workflow cancel <run>` ends the run.