agent-transport-system 0.3.49 → 0.4.0

package/skills/ats-cli/SKILL.md

@@ -1,322 +1,352 @@
 ---
 name: ats-cli-guide
-description: Official ATS quick-start and recovery guide for agents using ats start and ats space commands.
+description: Official public ATS guide for agents using the `ats` CLI to set up ATS, prepare local agents, work in Spaces, send Wake messages, trace delivery, and repair local state.
 ---
 
 # ATS CLI Guide
 
+Use this skill when a user asks you to operate ATS from the public `ats` CLI.
+This is a user-facing guide. Do not use internal developer commands, local repo
+commands, hidden APIs, database edits, or implementation details to prove ATS works.
+
 ## What ATS Is
 
-ATS is the realtime transport layer for human-agent collaboration.
-Work happens inside `spaces`.
-`ats` is the official CLI for signing in, choosing an ATS identity, connecting a local agent runtime, and creating, joining, watching, or sending messages in spaces.
+ATS is the Agent Transport System for human-agent collaboration.
 
-Most agents only need:
+- A Space is the shared room where people and agents talk.
+- A Human Profile is the user's ATS identity.
+- An Agent Profile is an AI teammate's ATS identity.
+- ATS Service is the local background service that lets Spaces wake agents on
+  this computer.
+- Preparing agents means making local agents such as Codex ready on this
+  computer.
+- Wake is not a separate command. Wake happens when a Space message mentions a
+  wakeable Agent Profile.
+- Trace explains what happened to one Wake or delivery attempt.
 
-1. `ats start`
-2. `ats space create`
-3. `ats space join`
-4. `ats space watch`
-5. `ats space send`
+## First Rule
 
-## Use This Skill When
+Use the same entry command the user used:
 
-1. The user wants to set up ATS for an agent or human.
-2. The user wants to create, join, watch, or send messages in an ATS space.
-3. An ATS command failed because of auth, profile, view, password, or space-target issues.
-4. You need exact ATS CLI syntax and should not guess.
+- If ATS is installed globally, use `ats ...`.
+- If the user started with `npx agent-transport-system ...`, keep using that
+  entry form until they install ATS globally.
 
-## Ignore This Skill When
+Examples below use `ats`.
 
-1. The task is not using ATS.
-2. The user is doing normal coding or shell work unrelated to ATS spaces.
-3. You do not need to run an `ats ...` command.
+## Install And Start
 
-## Core Terms
+Install ATS:
 
-1. `space`: the shared collaboration room where messages and live activity happen.
-2. `profile`: the ATS identity that joins a space.
-3. `view`: output mode for the current command. Use `agent` for machine-readable automation and `human` for interactive terminal UX.
-4. `controller`: the binding between an ATS agent profile and a local agent runtime such as Codex or Claude Code.
-5. `unbound`: a valid temporary state where an agent profile exists without a controller binding yet.
+```bash
+npm install -g agent-transport-system@latest
+```
 
-## Quick Start
+Start the normal setup flow:
 
-### Command entry rule
+```bash
+ats start
+```
 
-Keep follow-up commands on the same entry path the user used to launch ATS.
+Check available commands:
 
-- If the session started with an installed binary, keep using `ats ...`.
-- If the session started with `npx agent-transport-system ...`, keep using `npx agent-transport-system ...` for login/retry/next-step guidance unless the user has explicitly installed ATS globally.
+```bash
+ats --help
+ats <command> --help
+```
 
-In the command examples below, treat `ats` as the default installed-binary form.
-If the user started from `npx agent-transport-system ...`, substitute the same `npx ...` entry path when giving follow-up steps.
+## View Modes
 
-### Fastest closed loop
+- Use `--view human` for interactive, human-readable terminal flows.
+- Use `--view agent` for machine-readable Agent output.
+- If identity matters, pass `--profile <profile-id>` explicitly.
+- An Agent should use an Agent Profile, not a Human Profile.
 
-1. Check auth:
+Common checks:
 
 ```bash
 ats auth status --view agent
+ats whoami --view agent
+ats profiles list --view agent
+```
+
+## Sign In
+
+Human sign-in:
+
+```bash
+ats login --view human
 ```
 
-2. If needed, sign in:
+Automation with a one-time token:
 
 ```bash
-ats login --view agent --method ott --ott <token>
+ats login --method ott --ott <token> --view agent
 ```
 
-3. Check current ATS identity:
+Then verify:
 
 ```bash
+ats auth status --view agent
 ats whoami --view agent
 ```
 
-4. Start with an existing agent profile:
+## Profiles
+
+Create an Agent Profile:
 
 ```bash
-ats start --view agent --profile-id <profile-id>
+ats profiles create "Codex Agent" --kind agent --view agent
 ```
 
-5. Or create an agent profile in place:
+Use an existing Agent Profile during setup:
 
 ```bash
-ats start --view agent --kind agent --profile-name <profile-name>
+ats start --view agent --profile-id <agent-profile-id>
 ```
 
-6. Create a space:
+Create or select an Agent Profile through setup:
 
 ```bash
-ats space create --name <space-name> --profile <profile-id> --view agent
+ats start --view agent --kind agent --profile-name "Codex Agent"
 ```
 
-7. Join a space:
+Select a profile for the current terminal:
 
 ```bash
-ats space join <space-id> --profile <profile-id> --history-limit 100 --view agent
+ats profiles set <profile-id> --view agent
 ```
 
-8. Watch read-only:
+If a Space command fails because the active profile is not an Agent Profile,
+list profiles, copy an Agent Profile ID, and rerun with `--profile`:
 
 ```bash
-ats space watch <space-id> --profile <profile-id> --history-limit 100 --view agent
+ats profiles list --view agent
+ats space join <space-id> --profile <agent-profile-id> --view agent
 ```
 
-9. Send one message:
+## Prepare Local Agents
+
+Prepare local agents for an existing Agent Profile:
 
 ```bash
-ats space send <space-id> "<message>" --profile <profile-id> --view agent
+ats agents prepare --profile <agent-profile-id> --view agent
 ```
 
-If `whoami` reports no selected profile, create one or reuse one, then keep `--profile <profile-id>` explicit on every `ats space ...` command in fresh processes.
+Continue a Web handoff exactly as ATS Web tells the user:
 
-### Human `ats start` skills attention flow
+```bash
+ats agents prepare --start-session <opaque-token>
+```
 
-1. In human interactive `ats start`, when ATS reports `Skills Setup: Needs attention`, ATS first asks whether to `Install or update now` or `Skip for now`.
-2. If the user enters the install/update target picker from that prompt, the picker uses `Back` to return to the previous `Install or update now / Skip for now` decision instead of cancelling the whole `start` flow.
-3. If the user opens `Manual install guide`, ATS returns to the same `Install or update now / Skip for now` decision after the guide instead of continuing the rest of `start`.
-4. Cancelling either the top-level skills decision or the nested install flow cancels `ats start`; ATS must not silently treat cancel as `Skip for now`.
+Run Web single-command setup when ATS Web provides a Human Profile ID and token:
 
-### Human `ats start` disclaimer persistence
+```bash
+ats agents prepare --human-profile <human-profile-id> --ott <one-time-token>
+```
 
-1. Only an explicit interactive human acceptance may persist `disclaimerAcceptedVersion` for `start`.
-2. Agent-view notices and non-interactive human runs may display the disclaimer and continue, but they must not mark the disclaimer as accepted on behalf of a human.
+Useful local-agent commands:
 
-### Human `ats start` join handoff
+```bash
+ats agents detect --view agent
+ats agents list --view agent
+ats agents enable --all --view agent
+ats agents repair --agent <agent-id> --view agent
+ats agents show <agent-id> --view agent
+```
 
-1. In human interactive `ats start`, once the user has already chosen the ATS profile for this start session, the follow-up `Join a space` action must carry that same profile forward.
-2. This start-owned join handoff must not ask `Which profile should this join use?` again before space selection. Profile re-confirmation belongs to standalone `ats space join` / `ats space watch` entry flows, not the immediate `start -> join` continuation.
+What `prepare` means:
 
-### Human join profile workbench
+- It makes this computer ready to run local agents.
+- It may ask ATS Service to install, run, or refresh.
+- It does not create a Space.
+- It does not send a Wake message.
 
-1. In human interactive `ats start -> join` and standalone human `ats space join`, once the user chooses to bring other profiles, ATS opens one profile workbench instead of a separate `How would you like to add profiles?` branch prompt.
-2. The workbench is the single source of truth for that join attempt: existing selections and newly created profiles stay selected in-memory until the user explicitly chooses `Join this space with N selected profile(s)`.
-3. `Create a new profile` returns to the same workbench, auto-selects the created profile, and preserves any prior existing selections.
-4. `Back` from the workbench returns to the outer `Bring your agents or other profiles with you?` decision instead of committing any member changes.
-5. ATS applies add-members only once, at the final explicit join action from the workbench.
+## Spaces
 
-### Human ATS Service cleanup follow-up
+Create a Space:
 
-1. ATS now uses one shared service-participation gate for human interactive `ats start`, standalone `ats space join`, and create-and-join follow-ups.
-2. That gate only runs when ATS has real local wake-up value on this device (`keep_running` from the local-demand projection). If there are no wakeable local routes, ATS skips interactive service repair/start prompts.
-3. The shared gate owns all three service states for those flows:
-   - missing: `ATS Service is missing. Install it now?`
-   - not running: `ATS Service is not running. Start it now?`
-   - drift / cleanup required: `ATS Service needs cleanup. Repair it now?`
-4. Standalone `ats space` keeps the parent menu service-neutral. ATS waits until the user actually chooses a join/create-and-join path, then applies the shared gate inside the child flow.
-5. `ats space watch` is read-only. It no longer runs the interactive ATS Service gate.
+```bash
+ats space create --name "Project Room" --join --profile <profile-id> --view human
+```
 
-## Ask The Human Before Continuing
+Join a Space:
 
-1. You need a login token or device-login approval.
-2. You need a space password.
-3. You are not sure which `profile-id` or `space-id` the user wants.
-4. The command would delete data, reset ATS, uninstall ATS, or remove a profile.
+```bash
+ats space join <space-id> --profile <profile-id> --view human
+```
 
-## Guardrails
+Watch a Space read-only:
 
-### Identity and view safety
+```bash
+ats space watch <space-id> --profile <profile-id> --view agent
+```
 
-1. Never create a human profile for an agent identity.
-2. In agent self-setup, always include both `--view agent` and `--kind agent` for profile creation paths.
-3. Treat selected profile as session-scoped convenience only; in fresh or non-interactive processes, do not assume it persists and keep `--profile <profile-id>` explicit.
-4. For multi-agent collaboration, never depend on implicit selected profile; pass `--profile <profile-id>` per command.
-5. If profile kind is not compatible with agent view, stop and switch profile before joining spaces.
-6. Agent-view profile/controller rule: when creating or updating an agent profile, always choose the controller that matches the current runtime agent when supported (for example `codex -> codex`, `claude-code -> claude-code`).
-7. If the current runtime agent is not supported yet, continue as `unbound` (no controller) and explicitly tell the user this profile will join without controller until binding is configured.
-8. For builtin controllers, `controllerRef` should use `builtin:<id>`. Example: `ats profiles update <profile-id> --controller-kind builtin --controller-ref builtin:codex --controller-enabled true --view agent`.
+Send one message:
 
-### Space target safety
+```bash
+ats space send <space-id> --profile <profile-id> "hello"
+```
 
-1. Explicit space targets must be canonical `spaceId` (64-char hex), not space name.
-2. In non-interactive/agent flows, missing positional space target is an error by design.
-3. If space is password-protected, request password from the user; never fabricate or brute-force values.
+Send shell-sensitive or multiline text safely:
 
-### Deletion and destructive actions
+```bash
+MESSAGE="$(cat <<'EOF'
+your message content with `backticks` and $variables kept literal
+EOF
+)"
+ats space send <space-id> --profile <profile-id> "$MESSAGE"
+```
 
-1. `ats space delete` is human-only and requires interactive confirmation.
-2. Agent view cannot delete spaces directly.
-3. `ats reset` and `ats service uninstall` enforce strict teardown and can fail fast when teardown cannot complete.
+Or use file/stdin:
 
-### Output and replay expectations
+```bash
+ats space send <space-id> --profile <profile-id> --file /tmp/message.txt
+echo "hello" | ats space send <space-id> --profile <profile-id> --stdin
+```
 
-1. In agent view, join/watch runtime output is forced to `ndjson` even when `--output text` is requested.
-2. Current replay behavior is recent-history preload (`recent=1`) plus live stream; no in-process auto-reconnect.
-3. If `ats space join --view agent` starts without stdin, ATS still joins as a participant in stream-only mode; this is not `watch`.
-4. In that stream-only join mode, send follow-up messages with `ats space send <space-id> "<message>" --profile <profile-id> --view agent`.
-5. On disconnect, rerun `ats space join` or `ats space watch`.
+Read recent history:
 
-## Human operator note
+```bash
+ats space history <space-id> --profile <profile-id> --view agent
+```
 
-Use `--view human` or omit `--view` when a human TTY flow is intended.
-Keep explicit `--profile <profile-id>` in multi-agent or multi-terminal workflows.
+Read or update the Space guide:
 
-## Progressive Disclosure Map
+```bash
+ats space guide <space-id> --profile <profile-id>
+ats space guide set <space-id> "Keep replies concise." --profile <profile-id>
+ats space guide clear <space-id> --profile <profile-id>
+```
 
-Read only what is needed for the current step. Start here, then drill down:
+Add your own Agent Profile to a Space:
 
-1. Onboarding and identity lifecycle:
-   - `playbooks/agent-onboarding.md`
-2. Space operations and recovery playbook:
-   - `playbooks/space-ops.md`
-3. Full command reference (top-level + key subcommands):
-   - `references/commands.md`
-4. Runtime resolution semantics (base URL, profile, view, replay):
-   - `references/runtime-resolution.md`
+```bash
+ats space add-members <space-id> --member <agent-profile-id> --profile <human-profile-id>
+```
 
-Recommended reading order:
+Interactive Space controls:
 
-1. `SKILL.md` (this file)
-2. One playbook file matching the active task
-3. One reference file only if exact syntax or runtime semantics are needed
+- `Enter` sends.
+- `Shift+Enter` adds a newline.
+- `/` opens commands.
+- `@` mentions people or agents.
 
-## Quick Recovery
+## Wake An Agent
 
-### `authentication required`
+There is no `ats wake` command. Wake an agent by sending a Space message that
+mentions the Agent Profile.
 
-1. Run:
+Before Wake:
 
-```bash
-ats login --view human
-```
+1. The Agent Profile is a member of the Space.
+2. The local agent on this computer has been prepared.
+3. The user sends a normal Space message; do not create hidden work manually.
 
-or in automation with OTT token:
+Example:
 
 ```bash
-ats login --view agent --method ott --ott <token>
+ats space send <space-id> --profile <human-profile-id> "@Codex Agent please reply with one sentence."
 ```
 
-2. Re-run original command.
+A successful Wake should lead to a visible agent reply in the Space. If it does
+not, use trace.
+
+## Trace A Wake Or Delivery
 
-### `space.profile.required` or profile required guidance
+Use the trace command printed by ATS after a Wake or reply when available.
 
-1. If you do not have an agent profile yet, create one:
+Trace by client message:
 
 ```bash
-ats profiles create <profile-name> --kind agent --view agent
+ats service trace --space <spaceId> --client-message <clientMessageId> --target-profile <targetProfileId> --view agent
 ```
 
-2. Or select an existing profile explicitly for the current session:
+Trace by dispatch ID:
 
 ```bash
-ats profiles set <profile-id> --view agent
+ats service trace --space <spaceId> --dispatch <dispatchId> --view agent
 ```
 
-3. Retry the space command with explicit profile:
+Trace by source signal:
 
 ```bash
-ats space join <space-id> --profile <profile-id> --view agent
+ats service trace --space <spaceId> --source-signal <sourceSignalId> --target-profile <targetProfileId> --view agent
 ```
 
-### Hosted profile create `internal error`
-
-1. If `ats` fails while creating or updating a profile but the same flow works in `ats-dev`, treat it as a hosted auth issue first, not a local prompt mistake.
-2. The current recovery meaning is: the production auth deployment is likely behind the latest profile flow and needs the matching deploy/migration before retry.
-3. Do not workaround this by creating a half-configured agent profile without its intended controller binding unless the user explicitly accepts that degraded state.
+Rules:
 
-### Automatic upgrade failed
+- Always pass `--space`.
+- Pass exactly one of `--client-message`, `--dispatch`, or `--source-signal`.
+- If you use `--client-message` or `--source-signal`, also pass
+  `--target-profile` when ATS needs to know which Agent Profile was targeted.
 
-1. If ATS says automatic upgrade failed, use the manual fallback first:
+If you do not see a trace command, check Space history in Agent View and look
+for diagnostic fields or a printed trace command:
 
 ```bash
-npm install -g agent-transport-system@latest
+ats space history <space-id> --profile <profile-id> --view agent
 ```
 
-2. If ATS specifically says version metadata is missing, repair local state and retry:
+## Repair
+
+Diagnose first:
 
 ```bash
-ats reset --yes
-ats upgrade --check
+ats doctor --view human
+ats service status --view agent
+ats service snapshot --view agent
 ```
 
-### Wrong view mode behavior
-
-1. Force per-command view immediately:
+Refresh local agent readiness:
 
 ```bash
-ats --view agent <command>
+ats agents prepare --profile <agent-profile-id> --view agent
 ```
 
-2. Optional persistence for a known profile:
+Repair ATS Service:
 
 ```bash
-ats view agent --profile <profile-id>
+ats service reinstall
 ```
 
-### Lost streaming connection
+Run ATS Service in the current terminal only when the user intentionally wants a
+foreground service process:
 
-1. Re-run join/watch command.
-2. Keep `--history-limit <n>` to replay recent context.
-3. Keep explicit `--profile <profile-id>` in multi-process sessions.
-
-### Service installation recommendations shown at startup
+```bash
+ats service run
+```
 
-1. Install the local service if ATS says it is required:
+Repair local ATS data:
 
 ```bash
-ats service install
+ats repair local-state
 ```
 
-2. Check status:
+Last resort for this computer only:
 
 ```bash
-ats service status
+ats reset
 ```
 
-3. Continue the previous command.
+Ask before running `ats reset`, `ats uninstall`, `ats service uninstall`, profile
+deletion, or Space deletion.
 
-### Non-TTY missing expected details
+## What Not To Do
 
-If non-TTY output does not include the expected guided details, rerun in Human View
-from a TTY-capable terminal session when your agent can operate an interactive terminal:
+- Do not use internal developer commands or local repository commands.
+- Do not use hidden APIs, database edits, or handcrafted payloads.
+- Do not guess profile IDs, Space IDs, passwords, or one-time tokens.
+- Do not create a Human Profile for an Agent.
+- Do not treat a trace success line as a user-visible agent reply. Verify the
+  Space actually received the reply.
+- Do not use stale commands. Check `ats <command> --help` if unsure.
 
-```bash
-ats --view human <command>
-```
+## More Detail
 
-## Skill Notes
+Read only the topic needed for the current task:
 
-1. Keep command lines copy-ready and explicit.
-2. Prefer deterministic inputs over prompt fallback in agent flows.
-3. Read only as deep as needed. Most ATS tasks do not require the full command or runtime reference.
-4. For exact syntax or edge behavior, rely on the reference files listed above.
+- Agent setup: `playbooks/agent-onboarding.md`
+- Space operations: `playbooks/space-ops.md`
+- Exact command syntax: `references/commands.md`
+- Command context and view/profile behavior: `references/runtime-resolution.md`