@team-agent/installer 0.5.119 → 0.5.121

package/skills/team-agent/references/recovery-runbook.md

@@ -1,262 +1,111 @@
-# Team Agent Recovery Reference
+# Team Agent recovery reference
 
-This reference is for the Rust Team Agent runtime. This reference is a live document.
+Recover the selected team through public CLI evidence, not guessed bindings or old creation habits. Check that the chosen binary exposes `start`, `stop`, `team` and `agent` help. A reused candidate version string alone does not establish feature support. If missing, ask for an authorized supporting installation; do not switch binaries or rewrite state automatically.
 
-When a Team Agent framework problem appears, check this reference first. After the problem is resolved, update this reference before closing the work, whether or not the final fix used an existing entry here. New recovery advice may be added only after RS validation on a real Team Agent environment; unverified Python-only procedures stay out of this external reference.
+## Authority and non-destructive order
 
-## Validation Gate
+| Level | Who | Scope |
+|---|---|---|
+| L1 | Any agent | Read-only status/doctor/inbox, evidence and current-payload handoff |
+| L2 | Authorized Leader | Context-preserving team/agent lifecycle repair |
+| L3 | Explicitly authorized user/operator | Claim/takeover, intentional context discard, exceptional state/coordinator surgery |
 
-Every prescription below must carry an RS verification record. A command copied from Python 0.2.11 or from an incident note is not valid until it has been verified against the RS runtime. If RS behavior differs, document the RS behavior, not the Python behavior.
+A worker must not run L2/L3 because it can read this reference. Explicit child-team delegation still requires original caller admission and parent protection. Follow [nested teams](team-in-team.md).
 
-Use placeholders only:
+1. Diagnose at L1 in the exact workspace/team.
+2. Prefer proven resume with `--session preserve`.
+3. Stop on unknown, partial or capability refusal; do not reset, retry or adopt a replacement blindly.
+4. Only explicit user/operator authorization can permit context loss or binding surgery. Never broadly kill shared servers or edit another workspace.
 
-- `$WORKSPACE` for the team workspace
-- `$TEAM` for the active team key when a command needs one
-- `$AGENT_ID` for a worker id
-- `$TASK_ID` for a task id
+Use placeholders, not private paths: `$WORKSPACE`, `$TEAM`, `$AGENT_ID`, `$TASK_ID`.
 
-Do not write recipes that depend on a user's private absolute paths, private specification fields, or unverified local state.
+## 1. L1 read-only triage
 
-## Recovery Levels
-
-| Level | Who may run it | Scope | Misuse consequence |
-| --- | --- | --- | --- |
-| L1 | Any agent, including a worker | Read-only diagnosis, file report handoff, status/log/result inspection, current-payload E23 fallback only | Low risk, but must not mutate bindings or lifecycle state |
-| L2 | Leader only | Resume-oriented lifecycle repair such as restart of an existing team or worker | A worker running L2 must be treated as `worker.privilege_escalation_attempt` |
-| L3 | User/operator only | Claiming/taking over leader ownership, state surgery, coordinator respawn, fresh/reset | E19/#232 class risk: wrong workspace or pane can steal ownership or destroy context |
-
-Spine for every incident:
-
-1. Diagnose with L1 read-only commands.
-2. Prefer resume or repair that preserves context.
-3. Use L3 surgery only when the user/operator explicitly approves and the coordinator/write owner is controlled.
-4. Use fresh/reset only as the last resort.
-
-Fresh/reset red line:
-
-> WARNING: context will be lost. Run this only after diagnostics, resume, and repair have all failed and the user has explicitly typed approval. Do not make it the default. Each use must emit `recovery.context_reset` with source and approval timestamp.
-
-## Symptom Index
-
-| Symptom | Root cause family | Prescription |
-| --- | --- | --- |
-| Status is confusing, messages/results may be pending, or a worker says it cannot report | Need a safe read-only picture first | §1 L1 Read-Only Triage |
-| Leader pane exists but messages say `leader_not_attached`, `rebind_required`, `team_owner_mismatch`, or leader 被抢 | Leader ownership or receiver binding drift | §2 L3 Claim Or Rebind Leader |
-| A live team must be recovered without losing worker context | Resume/restart path needed | §3 L2 Restart With Resume First |
-| Shutdown/restart cleanup status is ambiguous | Need residue-based truth, not a single `ok` field | §4 L1/L2 Cleanup Verification |
-| MCP tool call fails with `Transport closed` while the worker still has the payload | Provider-owned MCP stdio child died | §5 MCP Transport-Dead Payload Handoff |
-
-## 1. L1 Read-Only Triage
-
-[contextual: preserved] [level: L1] Any agent may run this. It reads state only and does not mutate the team.
-
-Diagnosis:
-
-```bash
-team-agent status --workspace "$WORKSPACE" --json --detail
+```sh
+team-agent team status --workspace "$WORKSPACE" --team "$TEAM" --json
+team-agent doctor --workspace "$WORKSPACE" --team "$TEAM" --json
 team-agent inbox "$AGENT_ID" --workspace "$WORKSPACE" --team "$TEAM" -n 3 --json
 ```
 
-What to look for:
-
-- `leader_receiver.status`
-- `coordinator.status`
-- agent `status`
-- uncollected results
-- messages stuck in `accepted`, `failed`, or `rebind_required`
-
-Resume/repair:
-
-- If the answer identifies an L2/L3 condition, do not run the elevated command from a worker pane. Send the evidence to the leader/user.
-- If MCP reporting is broken, write a handoff artifact under the team's artifacts directory and tell the leader the relative path.
-
-Last resort:
-
-- None. This entry is read-only. Do not turn triage into fresh/reset.
-
-RS verification record:
+Status is the concise node projection: use `runtime_status`, `activity`, `health` and the reported attach target without inferring absent internals. An uncertain node also carries `observation_reason` and an explicitly scoped `next_action`; healthy nodes retain the compact existing fields. `--detail` is not a full historical dump. Follow doctor's actual owner/receiver/coordinator findings and recovery actions. Installed is not authenticated; unknown is not proven dead, stopped or unavailable.
 
-- `#249 Python 0.2.11 -> Rust 0.3.2 upgrade compatibility`: Rust `status`, `collect`, and `read` succeeded against an upgraded live team; restart resumed and post-restart MCP delivery worked. Evidence ledger: `dogfood-execution-ledger-T2.md`, case `#249`.
-- Mac mini LOOP/G1-G4 evidence also captured status and command outputs after restart/shutdown flows; see `g1g4-macmini-confirm-report.md`.
+Accepted/queued messages are not replies. Keep task/result/receiver evidence separate from transport acceptance. If the worker already has a report but MCP is broken, use the payload handoff contingency below rather than guessing it was delivered.
 
-Python 0.2.11 compatibility note:
+## 2. L3 claim or rebind only when diagnosed
 
-- Python teams used equivalent `status`/`collect` verbs. Python-specific wrapper paths are deprecated and are intentionally not listed here.
+Use only when diagnosis identifies owner/receiver binding drift and the intended Leader pane/workspace/team are verified. Do not use this to bypass a failed creation, resume or caller check:
 
-## 2. L3 Claim Or Rebind Leader
-
-[contextual: preserved] [level: L3] User/operator only. A worker must not run this. Misuse can steal the leader binding or recreate E19/#232 style ownership damage.
-
-Use this when L1 triage shows the leader pane is live but leader-bound delivery is blocked by ownership or receiver drift.
-
-Diagnosis:
-
-```bash
-team-agent status --workspace "$WORKSPACE" --json --detail
-```
-
-Confirm:
-
-- The current pane is the intended leader/operator pane.
-- The workspace is the intended team workspace.
-- The target team is the intended `$TEAM` when multiple teams share a workspace.
-
-Resume/repair:
-
-```bash
+```sh
 team-agent claim-leader --workspace "$WORKSPACE" --team "$TEAM" --json
 ```
 
-If the previous owner is live and the user explicitly approves stealing ownership, add the product's confirmation flag:
+If the previous owner is live, taking ownership additionally needs explicit user approval and the public confirmation flag:
 
-```bash
+```sh
 team-agent claim-leader --workspace "$WORKSPACE" --team "$TEAM" --confirm --json
 ```
 
-Validate:
-
-```bash
-team-agent status --workspace "$WORKSPACE" --json --detail
-```
-
-The receiver should be attached and new leader-bound delivery should no longer report `leader_not_attached`.
-
-Extreme surgery:
-
-- Do not edit binding fields by hand unless a user/operator has approved the exact state repair and the coordinator/write owner is stopped or otherwise controlled.
-
-Last resort:
-
-- Fresh/reset is not a leader claim repair. Do not use it here.
-
-RS verification record:
-
-- Dogfood T2 R2: old live team restart/claim/takeover passed from the persistent leader pane. Evidence ledger: `dogfood-execution-ledger-T2.md`, case `R2`.
-- RS #235 bug3 Mac mini run: `claim-leader` and `takeover` claimed live panes and persisted `leader_receiver.status="attached"` with `claimed_via="claim-leader"`. Evidence root id: `7b146ce-bug3-20260606T023011Z`.
-- G1-G4 report: help path for `claim-leader` exited 0 and did not trigger action validation. Evidence: `g1g4-macmini-confirm-report.md`, CR-063.
-
-Python 0.2.11 compatibility note:
-
-- Python had analogous claim/takeover verbs. Use RS commands above for RS teams.
-
-## 3. L2 Restart With Resume First
-
-[contextual: partial] [level: L2] Leader only. A worker must not run this. The goal is to preserve session context; resume is always before fresh.
-
-Use this when L1 triage shows a team or worker needs lifecycle repair but the state still carries enough runtime/session context to resume.
-
-Diagnosis:
-
-```bash
-team-agent status --workspace "$WORKSPACE" --json --detail
-```
-
-Resume/repair:
-
-```bash
-team-agent restart "$WORKSPACE" --team "$TEAM" --json
-```
-
-A single-worker clean-context reset is not a resume operation. Only after the user explicitly approves discarding that worker's session, use:
-
-```bash
-team-agent reset-agent "$AGENT_ID" --workspace "$WORKSPACE" --team "$TEAM" --discard-session --json
-```
+Recheck status/doctor and real Leader-bound delivery afterward. A command receipt alone is not actual client consumption. Do not clear CALLER/Leader identity or manually patch binding fields. State/coordinator surgery requires its own exact authorization and controlled write owner; it is not a normal recovery recipe.
 
-Validate:
+## 3. L2 restart with strict continuation first
 
-```bash
-team-agent status --workspace "$WORKSPACE" --json --detail
-team-agent inbox "$AGENT_ID" --workspace "$WORKSPACE" --team "$TEAM" -n 3 --json
+```sh
+team-agent team restart --session preserve --workspace "$WORKSPACE" --team "$TEAM" --json
+team-agent agent restart "$AGENT_ID" --session preserve --workspace "$WORKSPACE" --team "$TEAM" --json
 ```
 
-The expected result is `status="restarted"` or an equivalent running projection without duplicate-session errors. Do not treat a partial failure on one worker as permission to reset the whole team.
+Run the applicable operation, not both automatically. Single-seat restart preflights continuation/capabilities before stop and starts only after confirmed stop. Known missing capture/backing for existing context refuses before destruction. A genuinely never-used seat may still take its original first-fresh path; that is not evidence of remembered-context restoration.
 
-Extreme surgery:
+Team restart leaves explicitly stopped and paused seats alone. To intentionally wake the selected stopped non-paused roster, use:
 
-- If restart reports a resume-integrity refusal, stop and escalate. Do not silently rerun with fresh flags.
-
-Last resort:
-
-```bash
-# Last resort only; see red line at top of this reference.
-team-agent restart "$WORKSPACE" --team "$TEAM" --allow-fresh --json
+```sh
+team-agent start --workspace "$WORKSPACE" --team "$TEAM" --json
 ```
 
-WARNING: context will be lost. Run this only after diagnostics, resume, and repair have all failed and the user has explicitly typed approval. Do not make it the default. Each use must emit `recovery.context_reset` with source and approval timestamp.
-
-RS verification record:
-
-- Dogfood T2 R2: restart returned restarted and status after restart showed a running team. Evidence ledger: `dogfood-execution-ledger-T2.md`.
-- Dogfood #249: Rust restart resumed session `019e9ffd-c99c-7b60-bff3-9612ab35bcf5`, post-restart MCP delivery worked, and cleanup residue was 0. Evidence ledger: `dogfood-execution-ledger-T2.md`, case `#249`.
-- G1-G4 Mac mini reconfirmation: restart recovered the same fake team in CR-007, after acknowledge-idle context in CR-021, and in coordinator recovery context in CR-052. Evidence: `g1g4-macmini-confirm-report.md`.
-
-Python 0.2.11 compatibility note:
-
-- Python restart procedures are deprecated compatibility background only. For RS teams, use the RS commands above.
-
-## 4. L1/L2 Cleanup Verification
-
-[contextual: partial] [level: L1 for verification, L2 for shutdown command] A worker may inspect cleanup evidence. Only the leader should run lifecycle cleanup.
+This activation is not a repair fallback and must be authorized for the roster. It neither unpauses seats nor guesses around corrupt/spec-only/unknown state. A live no-op is not changed role-file synchronization or business readiness.
 
-Diagnosis:
+New restart defaults to **auto** when the option is omitted: proven resume or only the original legal fresh fallback. Auto can lose remembered context; it is not synonymous with preserve or reset. If strict continuation refuses, retain the receipt and escalate. Only if the user explicitly authorizes the possible loss may the Leader choose:
 
-```bash
-team-agent status --workspace "$WORKSPACE" --json --detail
+```sh
+team-agent team restart --session auto --workspace "$WORKSPACE" --team "$TEAM" --json
 ```
 
-Resume/repair:
+Unsupported native fresh/resume remains a refusal; do not change provider, force legacy fallback or repeatedly retry a partial/unknown generation. Validate actual node identities/session receipts and a natural worker reply before claiming recovery.
 
-- If a leader intentionally stops or shuts down a test team, verify by residue, not by a single top-level `ok` field.
-- For cleanup verification, inspect whether the team session is gone and whether residual process/session lists are empty in the command output or status evidence.
+## 4. L1 verification / L2 scoped stop
 
-Leader command:
+Only an authorized Leader stops the selected team:
 
-```bash
-team-agent shutdown --workspace "$WORKSPACE" --keep-logs --json
+```sh
+team-agent stop --workspace "$WORKSPACE" --team "$TEAM" --json
 ```
 
-Validate:
+Verify actual typed results, not just exit0:
+- Intended team session/panes and owned native/helper/coordinator processes have the expected terminal outcome.
+- Returned `residuals.sessions`, `residuals.processes` and `residuals.owned_files` are empty, with no unresolved degraded/unknown verification.
+- Where zero-removable-resource acceptance is required, independently check the frozen owned inventory, including sockets, twice. Keep predeclared native archives/evidence separate from live residuals.
+- Shared coordinator/Leader/sibling resources remain protected. A stopped last-team coordinator can be expected, not automatically a new defect.
 
-- `session_killed=true` is decisive for a session that was expected to be killed.
-- `residuals.sessions=[]` and `residuals.processes=[]` are decisive for cleanup.
-- A missing coordinator after a successful cleanup can be expected; do not classify it alone as a product failure.
+Do not manually unlink unknown sockets or kill shared tmux servers to manufacture success. Preserve a failing scene and its ownership/birth evidence.
 
-Extreme surgery:
+## 5. MCP transport-dead payload handoff
 
-- Do not manually kill shared tmux servers from a worker pane.
+If a worker already owns the current report payload and its MCP stdio transport closes before normal send/report acceptance, preserve the exact payload in a team-scoped handoff artifact and inform the Leader/user through the remaining authorized visible channel. Do not copy credentials or substitute a database write/manual answer for natural Leader consumption.
 
-Last resort:
+This L1 contingency is not a general alternate messaging system or permission for worker lifecycle repair. After an authorized restart/resume, return to the three normal MCP tools. Queued notification, server write and actual Leader receipt remain different evidence layers.
 
-- None. Cleanup verification is not a context reset path.
+## 6. Intentional clean context is not incident recovery
 
-RS verification record:
+Only after explicit user approval to discard that worker's association:
 
-- Dogfood T2 R3: quick-start with true Codex worker, MCP server live, shutdown returned `ok=true`, `session_killed=true`, endpoint `has-session` rc=1, and post MCP/node/codex/process residue lines were all 0. Evidence ledger: `dogfood-execution-ledger-T2.md`.
-- G1-G4 CR-005: stop returned `ok=true`, `status="stopped"`, `session_killed=true`; following shutdown reported missing without treating that alone as failure. Evidence: `g1g4-macmini-confirm-report.md`.
-
-Python 0.2.11 compatibility note:
-
-- Python cleanup notes may mention direct tmux commands. They are not listed here as RS recovery prescriptions.
-
-## 5. MCP Transport-Dead Payload Handoff
-
-[contextual: preserved] [level: L1] If the worker already has a leader-bound payload in hand and the MCP transport dies before the normal `send` or `report_result` path can accept it, preserve the payload in a file handoff artifact and ask for leader/user recovery through the visible channel that still works.
-
-After restart/resume, use the normal MCP tool path again. Do not treat file handoff as a general message path or as permission to run arbitrary L2/L3 recovery operations.
-
-Python 0.2.11 compatibility note:
-
-- Python MCP stdio EOF had no durable reconnect. File handoff was the practical fallback.
+```sh
+team-agent agent reset "$AGENT_ID" --workspace "$WORKSPACE" --team "$TEAM" --discard-session --json
+```
 
-## Held Out Of This Reference
+Warn that context will be lost. Each intentional fresh/reset must retain `recovery.context_reset` audit evidence with authorization source and timestamp; missing evidence is not permission to fabricate an event or claim approval. Preserve the actual result and do not claim every native archive was erased. Reset is never an automatic response to preserve refusal, permission prompts or partial replacement.
 
-[contextual: unknown] Python-only procedures from older incident notes are intentionally not included as external RS prescriptions:
+## Compatibility and validation scope
 
-- legacy roster block cloning
-- direct live runtime-state injection
-- raw coordinator respawn commands
-- direct tmux-server surgery
-- hard-coded runtime paths
+The old bare/explicit-path `restart` keeps its preserve default; `quick-start`, `shutdown` and suffixed agent commands remain compatibility bridges for existing scripts, not these daily recovery instructions. Do not mechanically rename scripts or rewrite historical receipts as if they used the new surface.
 
-These may be useful forensic background for maintainers, but each must pass the RS validation gate before becoming a user-facing recipe.
+The short start/stop/restart journey has isolated two-Pi lifecycle verification, including live no-op, held-seat preservation, both-seat activation and scoped cleanup. Automated fixtures cover continuation/backing/partial/native/mixed refusals. This is not a fresh all-provider same-session memory or all-platform acceptance claim. Earlier Rust resume/cleanup records retain their original scope in history; Python-only repair, roster cloning, raw state injection and direct server/coordinator surgery are not promoted into validated public recipes.

package/skills/team-agent/references/team-agent-operator.md

@@ -1,10 +1,114 @@
 # Team Agent operator reference
 
-The assistant you are using is the team **leader**. Workers are described by Markdown files in a team directory; use the CLI for lifecycle operations.
+Canonical source: `docs/reference/team-agent-operator.md`. The two packaged mirrors under `skills/team-agent/docs/reference/` and `skills/team-agent/references/` are byte-identical; update the source and synchronize both, never maintain divergent operating instructions.
 
-## Plain-text team
+<!-- command-coverage:normative-start -->
+## Normative command inventory and compatibility accountability
 
-Create a directory with `TEAM.md` and at least one `agents/*.md` file:
+The current daily forms below are coverage authorities, not permission to execute every command. Provider/permission choices, scope, caller, session and capability guards in this guide still apply. New forms remain honestly `declared_gap` until the strict source/assertion/negative-twin evidence exists; successful Help or a separate finite journey is not automatic promotion. Every compact-Skill command must belong to exactly one coverage bucket.
+
+### Current documented forms
+```text
+team-agent --version
+team-agent agent clone reviewer --as second-reviewer --workspace . --team project-team
+team-agent agent fork reviewer --as continued-reviewer --workspace . --team project-team
+team-agent agent remove reviewer --confirm --workspace . --team project-team
+team-agent agent reset reviewer --discard-session --workspace . --team project-team
+team-agent agent restart reviewer --session preserve --workspace . --team project-team
+team-agent doctor --workspace . --json
+team-agent inbox leader --workspace . --team project-team -n 3
+team-agent models --provider NAME
+team-agent profile init my-api --auth-mode compatible_api --workspace .
+team-agent restart reviewer --workspace . --team project-team
+team-agent route add pi -- --verbose
+team-agent route clear pi
+team-agent route disable
+team-agent route enable
+team-agent route set pi -- --mode rpc
+team-agent route show pi --json
+team-agent route status --json
+team-agent send reviewer "Review the current change and report the main risk." --workspace . --team project-team
+team-agent send reviewer "Review this change" --workspace . --team project-team
+team-agent start --from ./my-team --workspace . --team project-team
+team-agent start --from .team/current --workspace . --team project-team
+team-agent start --help
+team-agent start --workspace . --team project-team
+team-agent start analyst --provider pi --bypass false --prompt "Analyze the proposed change"
+team-agent start auditor --role-file /absolute/path/to/auditor.md
+team-agent start reviewer --effort high --bypass false
+team-agent start reviewer --effort high --bypass false --workspace . --team project-team
+team-agent start reviewer --workspace . --team project-team
+team-agent status --json
+team-agent stop --workspace . --team project-team --json
+team-agent stop reviewer
+team-agent stop reviewer --workspace . --team project-team
+team-agent team --help
+team-agent team restart --session preserve --workspace . --team project-team
+team-agent team restart --workspace . --team project-team
+team-agent team restart --workspace . --team project-team --json
+```
+
+### Retained compatibility and negative-probe forms — NOT daily recipes
+The following old argv remain in the closed-world catalog for existing scripts and historical tests. Some intentionally invalid or removed flag combinations are negative probes, not supported operational advice. Existing covered records keep their original evidence and are not renamed to imply new-command coverage.
+
+```text
+team-agent add-agent <agent> --role-file <file>
+team-agent add-agent reviewer --role-file .team/current/agents/reviewer.md --workspace .
+team-agent approvals
+team-agent approvals <agent_id>
+team-agent approvals [coder]
+team-agent attach-leader
+team-agent claim-leader
+team-agent claude
+team-agent clone-agent <source> --as <new>
+team-agent codex
+team-agent codex --dangerously-bypass-approvals-and-sandbox
+team-agent doctor
+team-agent fork-agent <source> --as <new>
+team-agent inbox <agent_id> -n 3
+team-agent inbox coder -n 3
+team-agent profile doctor <name> --workspace . --json
+team-agent profile init <name> --auth-mode subscription --workspace .
+team-agent profile init claude-default --auth-mode subscription --workspace .
+team-agent profile init codex-default --auth-mode subscription --workspace .
+team-agent profile init deepseek --auth-mode compatible_api --workspace .
+team-agent profile show <name> --workspace . --json
+team-agent profile show deepseek --workspace . --json
+team-agent quick-start
+team-agent quick-start ./roles --team-id alpha
+team-agent quick-start .team/alpha
+team-agent quick-start .team/current
+team-agent quick-start <dir>
+team-agent quick-start <plain-text-team-dir>
+team-agent remove-agent <agent> --workspace . --confirm
+team-agent reset-agent <agent> --discard-session
+team-agent restart
+team-agent restart .
+team-agent restart . --allow-fresh
+team-agent restart . --team <session_name_or_team_name>
+team-agent send --task task_initial "Start"
+team-agent send --watch-result
+team-agent send --watch-result coder "Do the bounded task"
+team-agent send TO MESSAGE
+team-agent send reviewer "..."
+team-agent send reviewer "Review this change"
+team-agent shutdown --workspace . --keep-logs
+team-agent start-agent <agent>
+team-agent start-agent <agent_id> --workspace .
+team-agent start-agent coder --workspace .
+team-agent status
+team-agent status --detail --json
+team-agent status coder
+```
+
+The exact test binary's root Help complements this marked inventory; it does not authorize model launches or convert untested forms into covered claims.
+<!-- command-coverage:normative-end -->
+
+Only the authorized Leader operates team lifecycle. Check the chosen binary's `start --help` and `team --help`; an old installed CLI or a reused candidate version string is not proof of the intuitive surface. Do not silently install, switch binaries or copy credentials to make an example work.
+
+## Configure once, use start/stop
+
+A source directory contains `TEAM.md` and at least one role:
 
 ```text
 my-team/
@@ -12,76 +116,105 @@ my-team/
   agents/reviewer.md
 ```
 
-`TEAM.md` contains the team goal. Each role file's body contains that worker's instructions. The filename stem (`reviewer`) is the default worker id. YAML frontmatter is optional; a role can be plain Markdown.
+The body of `TEAM.md` is the team goal. Each role body contains instructions; the filename stem is the default agent ID. Record the user's provider and boolean bypass decisions for a new plan. From the native Leader tool context in the workspace:
+
+```sh
+team-agent start --from ./my-team --workspace . --team project-team
+team-agent start --workspace . --team project-team
+team-agent send reviewer "Review the current change and report the main risk." --workspace . --team project-team
+team-agent inbox leader --workspace . --team project-team -n 3
+team-agent stop --workspace . --team project-team --json
+```
+
+Creation needs complete configuration; start is not automatic template generation or state repair. Later start starts stopped non-paused members, including explicitly stopped members, and leaves verified live/drift-free instances unchanged. A no-op does not synchronize role bodies, apply new launch settings or prove tool/business readiness. A queued send is not completion; wait for a natural reply/result.
+
+## Scope and deterministic targets
 
-From a tmux-addressable terminal or supported agent pane, run commands in the workspace root (the parent of `my-team`):
+- Pin `--workspace PATH` and `--team KEY` when operating outside the selected team, across workspaces or when several teams exist.
+- `start reviewer.v2` is an agent, even if that directory exists. Team sources use `--from DIR`, `team start DIR` or explicit path syntax such as `./my-team`.
+- `restart ID` selects an agent; a same-named directory causes conservative refusal. `agent restart ID` removes the ambiguity.
+- Explicit missing paths, unknown flags, conflicts and extra arguments refuse; do not try a guessed CWD or takeover instead.
+- `--dry-run` on start/restart has no lifecycle effects. A proposed plan is not final lock-held admission. No eligible targets returns nonzero with the selected scope and skipped seats, not a successful start.
+
+## User decisions and compatibility
+
+Do not silently pick provider, model, effort or bypass. False preserves native permissions; it is not a read-only or sandbox guarantee. Use supported `models --provider NAME` discovery and retain exact model IDs.
+
+Traditional minimal Markdown remains accepted by the original compiler. Its compatibility interpretation is **not a default for a new user plan**: provider defaults to Pi, bypass to false, and unset model/effort are left to the provider. Team Agent does not infer a role model from TEAM defaults. Legacy explicit TEAM provider_effort remains supported for non-Pi roles; do not invent an effort for unspecified roles.
+
+Supported role metadata:
+- `agent_id` (legacy `name`) and `role` identify the seat.
+- `provider`, `model`, `effort`, and boolean `dangerously_skip_permissions` select intentional launch settings.
+- `auth_mode` and `profile` refer to local provider configuration.
+- `communication_mode` selects an admitted communication contract.
+- Historical `tools`, `permission_mode` and `label` do not restrict worker tools or permissions.
+
+## Add or wake with start
+
+A RoleOnly seat can be registered from its complete role file. A genuinely absent ID needs a complete file or explicit provider/bypass choices. These Pi/false values are examples of user decisions, not defaults:
 
 ```sh
-team-agent quick-start my-team
-team-agent send reviewer "Review the current change and report the main risk."
-team-agent inbox reviewer -n 3
-# The role file already records the user's provider and bypass choices.
-team-agent add-agent analyst --role-file /absolute/path/to/analyst.md
-team-agent shutdown --workspace .
+team-agent start auditor --role-file /absolute/path/to/auditor.md
+team-agent start analyst --provider pi --bypass false --prompt "Analyze the proposed change"
 ```
 
-A successful `send` can mean only accepted or queued. Wait for the worker's actual reply/result; acceptance is not completion. Use `team-agent status --json` to inspect readiness. `ok: true` with `ready: false` means the command succeeded but the team is not ready; follow the reported action.
+An imported external role goes into this team's `agents/ID.md`; the original stays untouched. A file already at that destination is used in place. Equal file/CLI definitions are accepted; conflicting provider/model/effort/bypass/prompt/profile values refuse before writes/startup. Omitted model, effort, profile and role body remain unchanged.
+
+Use `agent add` when explicitly requesting strict add-only behavior. It creates and starts a new seat but refuses an occupied ID, including stopped seats. Its disaster-recovery `--force` still requires a positively dead registered old pane and no live target cohort; a live or unknown target refuses. Force is not a role-update or routine restart shortcut.
+
+## Change a registered seat
 
-## User decisions and legacy compatibility
+```sh
+team-agent stop reviewer --workspace . --team project-team
+team-agent start reviewer --effort high --bypass false --workspace . --team project-team
+```
 
-For a new team plan, explicitly record each user's provider and bypass decisions; do not silently select either. Existing file-based compilation remains compatible, including minimal documents. The following table describes legacy interpretation, not defaults to choose on the user's behalf:
+Stop first before applying edited instructions or launch settings. A running seat with requested changes or known drift refuses rather than claiming a successful no-op. `--prompt` replaces permanent role instructions, not a one-time task; send one-time work with `send`. `--bypass` requires explicit true/false. Matching provider is allowed, but changing engines, even by file edits, is refused; use a new ID.
 
-| Setting | Default behavior |
-|---|---|
-| `provider` | `pi` |
-| `model` | Unset by Team Agent; leave model selection to the provider |
-| `effort` | Unset by Team Agent; leave effort selection to the provider |
-| `dangerously_skip_permissions` | `false`; preserve native permissions |
+The original role/spec transaction and provider admission remain authoritative. A failure is not an applied update; never assume a partial/unknown native replacement was rolled back or is safe to retry. Inspect the exact scoped receipt, status and doctor first.
 
-Do not invent `model: null` or `effort: max`. Record the user's bypass decision explicitly in a new role, even when it is false. The absence of a model or effort override is not a promise about what the provider's own UI eventually displays. Team Agent does not fill role model from TEAM-level defaults. An unspecified role effort defaults to None (native); for non-Pi roles, a legacy explicit TEAM provider_effort remains supported for compatibility.
+## Restart and session policy
 
-Optional supported role metadata:
+```sh
+team-agent restart reviewer --workspace . --team project-team
+team-agent team restart --workspace . --team project-team
+# Strict continuation: refuse before stop if known continuation evidence is absent.
+team-agent agent restart reviewer --session preserve --workspace . --team project-team
+team-agent team restart --session preserve --workspace . --team project-team
+```
 
-- `agent_id` (or legacy `name`) and `role` for identity.
-- `provider`, `model`, and `effort` to explicitly choose supported provider settings.
-- `auth_mode` and `profile` to use a provider profile.
-- `dangerously_skip_permissions: true` or `false` records the user's explicit permission choice. False preserves native permissions; it is not a read-only or sandbox guarantee.
-- `communication_mode` to select a supported worker communication contract.
+New agent/team restart defaults to **auto**: proven resume when possible, otherwise only the provider's existing legal fresh path. Auto is not a guarantee of saved memory, reset permission or a fallback around native capability refusal. Preserve requests strict continuation. The old bare/explicit-path restart bridge retains its original preserve default and output.
 
-Unknown and historical role keys are ignored, not used as a way to restrict tools or permissions. In particular, `tools`, `permission_mode`, and `label` do not configure a worker through role frontmatter.
+Single-agent restart checks scope, role/session backing and capabilities before stop; only confirmed stop allows start. On partial failure, report actual completed steps and inspect; do not blindly reset or replay. Team restart does not reactivate explicitly stopped or paused seats. Whole-team start intentionally activates the selected non-paused roster; neither command silently unpauses.
 
-## Add and start
+## Explicit agent operations
 
-`add-agent ID --provider NAME --bypass true|false` creates and starts a new seat without a prepared file. A traditional `add-agent ID --role-file FILE` needs no repeated flags when the file already defines provider and boolean bypass. Missing decisions may be supplied by CLI; equal file/CLI values are accepted, but conflicting definitions (including model, effort, prompt and profile) are rejected before writing or startup. Model, effort, prompt and profile remain optional. External role-file inputs are imported into the selected team's `agents/ID.md`; the original stays untouched. A file already there is used in place. Ordinary add rejects occupied IDs. Explicit `--force` is restricted to disaster recovery: the registered old pane must be positively confirmed dead and the target must have no live cohort. Live or unknown targets remain refused; the existing force-recreate transaction is reused, not a general update/implicit-restart path.
+```sh
+team-agent agent remove reviewer --confirm --workspace . --team project-team
+# Only after explicit authorization to discard this worker's context:
+team-agent agent reset reviewer --discard-session --workspace . --team project-team
+team-agent agent clone reviewer --as second-reviewer --workspace . --team project-team
+team-agent agent fork reviewer --as continued-reviewer --workspace . --team project-team
+```
 
-`start-agent ID` starts an existing stopped seat; it refuses a running seat, so use `stop-agent ID` first. Optional model, effort, bypass, prompt and profile update that same role document. Omitted fields and body are preserved; prompt replaces the body. A matching provider is allowed; any engine change, including manual file edits, is refused. Startup failure restores role and runtime spec bytes, and reports failure. File edits followed by start use the same compiler reload path.
+Remove/reset/clone/fork retain original confirmation, ownership and provider-capability gates. Clone copies configuration; fork is a new-seat continuation only where admitted. `--in-place` is unsupported. Unsupported native lifecycle is a refusal, never permission to silently use a legacy engine. Reset does not erase every native provider archive and must not be incident recovery's first response.
 
 ## Profiles and custom models
 
-A profile keeps provider credentials, endpoint settings, and optional model settings outside role text. This supports subscription profiles and custom/third-party API models, including Claude Code-compatible providers. Once an external role is imported, profile lookup uses the current team's/workspace's `profiles`, not the external source directory. Prepare the profile locally through public commands; do not discover or copy external credentials.
-
-Create a local profile, then edit its generated file on the user's machine:
+Profiles keep authentication/endpoints outside role text. Imported roles use this team's/workspace's profiles, not the external role's original directory. Prepare a named profile locally through public commands; never discover, copy or print external credentials:
 
 ```sh
 team-agent profile init my-api --auth-mode compatible_api --workspace .
 ```
 
-Reference it without copying secrets into Markdown:
+A role may explicitly reference `auth_mode: compatible_api` and `profile: my-api`, with the user's chosen provider/bypass. Profile model applies only when the role has no explicit override. Subscription and custom-API capabilities differ; follow actual provider admission, not a generic promise.
 
-```yaml
----
-provider: claude_code
-dangerously_skip_permissions: false
-auth_mode: compatible_api
-profile: my-api
----
-Use the configured provider to complete the assigned task.
-```
+## Observe and finish
 
-The profile can supply its model when the role has no explicit `model`; an explicit role model remains an override. Use `team-agent models --provider <provider>` to discover provider model IDs when choosing one explicitly. Never print or paste profile secrets into chat or role files.
+`status` / `team status` expose the concise node projection; `--detail` does not restore historical internal dumps. Use `doctor` for diagnosis. Check actual readiness and returned recovery actions; unknown evidence is not a stopped/live proof. Stop with `stop --workspace PATH --team KEY --json` and verify scoped residual sessions, processes and owned files. Protect parent/sibling/shared resources.
 
-## Help and worker communication
+Workers have only `send_message`, `report_result` and optional `get_team_status`. Report completion through `report_result`; do not promote a worker to lifecycle operator. See [nested teams](https://github.com/Florious95/team-agent/blob/main/skills/team-agent/references/team-in-team.md) and [recovery](https://github.com/Florious95/team-agent/blob/main/skills/team-agent/references/recovery-runbook.md).
 
-Use `team-agent --help` or a command's `--help` for the installed CLI syntax. Worker MCP exposes `send_message`, `report_result`, and `get_team_status`; workers use `report_result` to return completion. Nested-team guidance is in [team-in-team.md](team-in-team.md).
+## Legacy command bridges
 
-Keep role instructions in Markdown. Record explicit provider/bypass decisions for new plans, and add other metadata only for intentional settings; do not copy internal state fields into roles.
+Existing scripts may retain `quick-start`, `shutdown`, and `add-agent/start-agent/stop-agent/remove-agent/reset-agent/clone-agent/fork-agent`. These are compatibility interfaces, not the daily workflow. Use the short/team/agent forms above for new instructions. Do not mechanically rename scripts: legacy start refuses a live seat, new start can prove a no-op; bare/explicit-path legacy restart preserves its default. Old normal command output and failure evidence remain authoritative.