agent-transport-system 0.3.49 → 0.4.0

package/skills/ats-cli/playbooks/agent-onboarding.md

@@ -1,186 +1,114 @@
 # Agent Onboarding Playbook
 
-## Purpose
+Use this when an external Agent needs to set up or recover ATS identity and
+local-agent readiness with the public `ats` CLI.
 
-Use this playbook to bootstrap or recover ATS agent operation with minimal ambiguity.
-This playbook covers `auth`, `start`, `profiles`, and `view` in one closed loop.
+## Goal
 
-Use it after you already know the task is ATS setup.
-If the user is not trying to use ATS, stop here and do not apply this playbook.
+End in this state:
 
-## Preconditions
+1. The user is signed in.
+2. The Agent has an Agent Profile.
+3. This computer is prepared to run the local agent.
+4. The Agent can join a Space and be woken by a normal Space message.
 
-1. ATS CLI is installed and executable as `ats`.
-2. User can provide authentication token when needed.
-3. You can run commands in the target terminal session.
-4. You know which ATS profile should be reused or created.
+## Setup From Zero
 
-## Fast Path (Existing Agent Profile)
-
-1. Check auth and identity:
-
-```bash
-ats auth status --view agent
-ats whoami --view agent
-```
-
-2. Start with explicit existing profile:
+Install ATS if needed:
 
 ```bash
-ats start --view agent --profile-id <profile-id>
+npm install -g agent-transport-system@latest
 ```
 
-3. Optional: persist default view for this profile:
+Sign in:
 
 ```bash
-ats view agent --profile <profile-id>
+ats login --view human
 ```
 
-## Create Path (New Agent Profile)
-
-1. Ensure auth:
+Check identity:
 
 ```bash
 ats auth status --view agent
+ats whoami --view agent
 ```
 
-If not authenticated:
-
-```bash
-ats login --view agent --method ott --ott <token>
-```
-
-2. Create and select profile in one step:
-
-```bash
-ats start --view agent --kind agent --profile-name <profile-name>
-```
-
-Alternative explicit create path:
-
-```bash
-ats profiles create <profile-name> --kind agent --view agent
-ats profiles set <profile-id> --view agent
-```
-
-3. Verify:
-
-```bash
-ats whoami --view agent --profile <profile-id>
-```
-
-Profile/controller guidance in agent view:
-
-1. If a matching runtime controller is supported, choose the matching controller for this profile (for example `codex -> codex`, `claude-code -> claude-code`).
-2. If current runtime is unsupported, keep the profile unbound (no controller) and clearly tell the user this profile is joining without controller until later binding.
-3. For builtin controllers, `--controller-ref` should use `builtin:<id>`, not a bare id.
-
-## Profile Lifecycle (Operational)
-
-### List
+Run setup interactively for a human:
 
 ```bash
-ats profiles list --view agent
+ats start --view human
 ```
 
-### Set current profile
+Run setup as an Agent with an existing Agent Profile:
 
 ```bash
-ats profiles set <profile-id> --view agent
+ats start --view agent --profile-id <agent-profile-id>
 ```
 
-### Update profile name or controller binding
+Create an Agent Profile during setup:
 
 ```bash
-ats profiles update <profile-id> --name <new-profile-name> --view agent
+ats start --view agent --kind agent --profile-name "Codex Agent"
 ```
 
-Controller binding example:
-
-```bash
-ats profiles update <profile-id> --controller-kind builtin --controller-ref builtin:<controller-id> --controller-enabled true --view agent
-```
+## Prepare This Computer
 
-### Delete profile (explicit target)
+Prepare local agents for an Agent Profile:
 
 ```bash
-ats profiles delete <profile-id> --force --view agent
+ats agents prepare --profile <agent-profile-id> --view agent
 ```
 
-## View Management
-
-### One-off per command (recommended for automation)
+If ATS Web gives a handoff command, run that exact command. Common forms:
 
 ```bash
-ats --view agent <command>
+ats agents prepare --start-session <opaque-token>
+ats agents prepare --human-profile <human-profile-id> --ott <one-time-token>
 ```
 
-### Persist view for a profile
-
-```bash
-ats view agent --profile <profile-id>
-```
+Do not replace Web handoff with hidden API calls. The Web-provided command is
+the user-visible path.
 
-### Query current configured view
+## Verify Local Agents
 
 ```bash
-ats view
+ats agents detect --view agent
+ats agents list --view agent
+ats service status --view agent
 ```
 
-## Failure Recovery
-
-### Error: authentication required
-
-1. Authenticate:
+If ATS says local agents are not ready, run:
 
 ```bash
-ats login --view human
+ats agents prepare --profile <agent-profile-id> --view agent
 ```
 
-or
+If ATS Service is missing, stopped, or stale, follow the user-visible prompt or
+run:
 
 ```bash
-ats login --view agent --method ott --ott <token>
+ats service reinstall
 ```
 
-2. Retry original command.
-
-Ask the human before continuing if you need a token, device-login approval, or confirmation that sign-in should happen in the current environment.
+Use `ats service run` only when the user wants ATS Service running in the
+current terminal.
 
-### Error: agent view requires explicit profile argument
+## Identity Guardrails
 
-1. Provide explicit profile in the command.
-2. If unknown, list profiles first:
+- An Agent must use an Agent Profile.
+- A Human Profile is for the human user.
+- In automation, keep `--profile <profile-id>` explicit.
+- If you are unsure which profile to use, ask the user or run:
 
 ```bash
 ats profiles list --view agent
 ```
 
-### Error: profile kind mismatch in agent view
-
-1. Switch to an `agent` profile:
-
-```bash
-ats profiles set <agent-profile-id> --view agent
-```
-
-2. Retry command with explicit `--profile <agent-profile-id>`.
-
-### Error: missing profile during view persistence
-
-1. Persist with explicit profile:
-
-```bash
-ats view agent --profile <profile-id>
-```
-
-2. Or keep using per-command `--view agent`.
+## Ask The User Before Continuing
 
-## Operational Rules
+Ask first when:
 
-1. In multi-process collaboration, always pass `--profile <profile-id>`.
-2. Do not create or use human profiles in agent automation paths.
-3. Treat `ats start` as the canonical setup entrypoint.
-4. Keep setup commands deterministic and copy-ready.
-5. Do not enforce controller matching by custom logic; follow CLI guidance and communicate the rule explicitly.
-6. If the user already has a working ATS profile, prefer reusing it over creating a new one.
+- login requires browser approval or a one-time token;
+- the command needs a Space password;
+- multiple profiles or Spaces match;
+- the next command would reset, uninstall, delete, or remove anything.

package/skills/ats-cli/playbooks/space-ops.md

@@ -1,194 +1,129 @@
 # Space Operations Playbook
 
-## Purpose
+Use this when an external user or Agent needs to create, join, read, send, or
+diagnose ATS Space activity with the public `ats` CLI.
 
-Use this playbook to run `space` commands safely in human and agent workflows.
-This playbook covers create, join, watch, send, history, guide, password, and delete.
+## Basic Rules
 
-Use this playbook only when the task is explicitly about ATS spaces.
-For most agent flows, the core commands are `create`, `join`, `watch`, and `send`.
+- A Space ID is a 64-character hex string.
+- Use explicit `--profile <profile-id>` in Agent or multi-terminal workflows.
+- Ask the user for a Space password when needed. Do not guess.
+- Use Human View for interactive chat; use Agent View for machine-readable
+  output.
 
-## Universal Rules
+## Create Or Join
 
-1. Explicit target must be `<space-id>` (64-char hex), not space name.
-2. In agent/non-interactive mode, missing space target fails by design.
-3. Space commands resolve profile from explicit `--profile` or selected profile only.
-4. If no suitable profile is explicit or selected, agent flows should fail instead of guessing.
-5. In agent view, join/watch runtime output is forced to `ndjson`.
-
-## Ask The Human Before Continuing
-
-1. You need a protected-space password.
-2. You do not know the right `space-id`.
-3. The user did not confirm which ATS profile should join or send.
-4. The action is `space delete`.
-
-## Create
-
-### Create and optionally auto-join
+Create a Space:
 
 ```bash
-ats space create --name <space-name> --join --profile <profile-id> --view agent
+ats space create --name "Project Room" --join --profile <profile-id> --view human
 ```
 
-### Create password-protected space
+Join a Space:
 
 ```bash
-ats space create --name <space-name> --password <space-password> --profile <profile-id> --view agent
+ats space join <space-id> --profile <profile-id> --view human
 ```
 
-Notes:
-
-1. `--password` minimum length is 6.
-2. Password can include numbers, letters, and symbols.
-3. Password cannot be viewed or recovered later.
-
-## Join / Watch
-
-### Join
+Watch read-only:
 
 ```bash
-ats space join <space-id> --profile <profile-id> --history-limit 100 --view agent
+ats space watch <space-id> --profile <profile-id> --view agent
 ```
 
-### Join with role fields and mention alias
+Add one of your Agent Profiles to the Space:
 
 ```bash
-ats space join <space-id> --profile <profile-id> --history-limit 100 --role <role> --role-instructions <instructions> --mention-alias <alias-token> --view agent
+ats space add-members <space-id> --member <agent-profile-id> --profile <human-profile-id>
 ```
 
-### Watch read-only
+## Send Messages
 
-```bash
-ats space watch <space-id> --profile <profile-id> --history-limit 100 --view agent
-```
-
-### Join/watch protected spaces
+Send one line:
 
 ```bash
-ats space join <space-id> --profile <profile-id> --password <space-password> --view agent
-ats space watch <space-id> --profile <profile-id> --password <space-password> --view agent
+ats space send <space-id> --profile <profile-id> "hello"
 ```
 
-## Send / History / Guide
-
-### Send text
+Send multiline or shell-sensitive content safely:
 
 ```bash
-ats space send <space-id> "<message>" --profile <profile-id> --view agent
+ats space send <space-id> --profile <profile-id> --file /tmp/message.txt
 ```
 
-### Send from stdin
+or:
 
 ```bash
-echo "<message>" | ats space send <space-id> --stdin --profile <profile-id> --view agent
+cat /tmp/message.txt | ats space send <space-id> --profile <profile-id> --stdin
 ```
 
-### Send from file
+## Wake An Agent
 
-```bash
-ats space send <space-id> --file <utf8-file-path> --profile <profile-id> --view agent
-```
+There is no separate Wake command. Wake happens when a Space message mentions a
+wakeable Agent Profile.
 
-### Read history
+Before sending:
 
-```bash
-ats space history <space-id> --limit 20 --profile <profile-id> --view agent
-```
+1. The Agent Profile is a Space member.
+2. The local agent is prepared on this computer.
+3. The message is sent through normal Space UI or `ats space send`.
 
-### Read history as ndjson envelopes
+Example:
 
 ```bash
-ats space history <space-id> --limit 20 --json --profile <profile-id> --view agent
+ats space send <space-id> --profile <human-profile-id> "@Codex Agent please reply with one sentence."
 ```
 
-### Read guide
+## Read And Diagnose
 
-```bash
-ats space guide <space-id> --profile <profile-id> --view agent
-```
-
-### Update guide
-
-```bash
-ats space guide set <space-id> "<guide-text>" --profile <profile-id> --view agent
-```
-
-### Clear guide
+Read recent history:
 
 ```bash
-ats space guide clear <space-id> --profile <profile-id> --view agent
+ats space history <space-id> --profile <profile-id> --view agent
 ```
 
-## Password Management
-
-### Set or reset password
+Read Space status:
 
 ```bash
-ats space password <space-id> --password <new-space-password> --profile <profile-id> --view agent
+ats space status <space-id> --profile <profile-id> --view agent
 ```
 
-### Clear password
+Trace one Wake or delivery:
 
 ```bash
-ats space password <space-id> --clear --profile <profile-id> --view agent
+ats service trace --space <spaceId> --client-message <clientMessageId> --target-profile <targetProfileId> --view agent
 ```
 
-## Delete (Human-only)
-
-Delete requires human interactive confirmation and human profile context.
-Do not run this in agent view.
+If you have a dispatch ID:
 
 ```bash
-ats space delete <space-id> --profile <human-profile-id> --view human
+ats service trace --space <spaceId> --dispatch <dispatchId> --view agent
 ```
 
-## Alias Commands
+## Space Guide
 
-### Send alias
+Read the guide:
 
 ```bash
-ats send "<message>" --space <space-id> --profile <profile-id> --view agent
+ats space guide <space-id> --profile <profile-id>
 ```
 
-### Tail alias (`space history`)
+Set the guide:
 
 ```bash
-ats tail --space <space-id> --limit 20 --profile <profile-id> --view agent
+ats space guide set <space-id> "Keep replies concise." --profile <profile-id>
 ```
 
-## Failure Recovery
-
-### Error: profile required
-
-1. Select profile first:
+Clear the guide:
 
 ```bash
-ats profiles set <profile-id> --view agent
+ats space guide clear <space-id> --profile <profile-id>
 ```
 
-2. Retry with explicit `--profile <profile-id>`.
-
-### Error: invalid space target
-
-1. Verify the target is 64-char hex `spaceId`.
-2. Replace space name with `spaceId` and retry.
-
-### Error: space password required / invalid
-
-1. Ask user for current password.
-2. Retry with `--password <space-password>`.
-
-### Disconnect during join/watch
-
-1. Re-run `join` or `watch`.
-2. Keep `--history-limit <n>` for catch-up context.
-3. Keep explicit `--profile <profile-id>` in multi-process sessions.
-
-## Operational Recommendations
+## Recovery
 
-1. Keep `--history-limit` explicit in automation (`100` is default, `0` disables preload, max `500`).
-2. Prefer explicit profile on every `space` command.
-3. Use `watch` for monitor-only workflows.
-4. Use `send` for one-shot output and `join` only when live interactive stream is required.
-5. If the user says a space name instead of a `space-id`, ask for the actual `space-id` instead of guessing.
+- If the profile is wrong, rerun with explicit `--profile <profile-id>`.
+- If an Agent cannot reply, run `ats agents prepare --profile <agent-profile-id> --view agent`.
+- If ATS Service is not running, run `ats service status --view agent`, then
+  follow the prompt or run `ats service reinstall`.
+- If the stream disconnects, rerun `ats space join` or `ats space watch`.