agent-transport-system 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "agent-transport-system",
-  "version": "0.2.1",
+  "version": "0.2.3",
+  "atsReleaseDate": "2026-03-12",
   "description": "Agent Transport System CLI - https://ats.sh",
   "license": "MIT",
   "type": "module",

package/skills/ats-cli/SKILL.md

@@ -1,23 +1,44 @@
 ---
 name: ats-cli-guide
-description: Task-first ATS CLI guide for ats start and ats space join in --view agent, including profile required recovery and command routing.
+description: Official ATS quick-start and recovery guide for agents using ats start and ats space commands.
 ---
 
 # ATS CLI Guide
 
-## Scope
+## What ATS Is
 
-This skill is the official consumer guide for ATS CLI usage in real user sessions.
-It is optimized for agent execution and human-agent collaboration in North America production-style workflows.
+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.
 
-Use this skill when users ask how to:
+Most agents only need:
 
-1. Start ATS safely (`ats start`) in human or agent view.
-2. Join, watch, send, and manage spaces (`ats space join`, `ats space watch`, `ats space send`).
-3. Recover from profile/view/runtime issues (for example: profile required, auth required).
-4. Find exact command syntax without relying on guesswork.
+1. `ats start`
+2. `ats space create`
+3. `ats space join`
+4. `ats space watch`
+5. `ats space send`
 
-Do not use this skill as a contributor development contract for changing ATS CLI source code.
+## Use This Skill When
+
+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.
+
+## Ignore This Skill When
+
+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.
+
+## Core Terms
+
+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.
 
 ## Quick Start
 
@@ -31,70 +52,70 @@ Keep follow-up commands on the same entry path the user used to launch ATS.
 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.
 
-### Preflight
+### Fastest closed loop
 
-1. Confirm auth state:
+1. Check auth:
 
 ```bash
 ats auth status --view agent
 ```
 
-2. If not authenticated, run:
+2. If needed, sign in:
 
 ```bash
 ats login --view agent --method ott --ott <token>
 ```
 
-3. Confirm identity state:
+3. Check current ATS identity:
 
 ```bash
 ats whoami --view agent
 ```
 
-4. If `whoami` reports no selected profile, either create one or reuse one, then keep passing `--profile <profile-id>` on every `ats space ...` command in fresh processes.
-
-### Agent setup and entry
-
-1. Reuse an existing agent profile:
+4. Start with an existing agent profile:
 
 ```bash
 ats start --view agent --profile-id <profile-id>
 ```
 
-2. Or create one in-place:
+5. Or create an agent profile in place:
 
 ```bash
 ats start --view agent --kind agent --profile-name <profile-name>
 ```
 
-3. Create a space with an explicit profile:
+6. Create a space:
 
 ```bash
 ats space create --name <space-name> --profile <profile-id> --view agent
 ```
 
-4. Join a space with explicit profile and history preload:
+7. Join a space:
 
 ```bash
 ats space join <space-id> --profile <profile-id> --history-limit 100 --view agent
 ```
 
-5. Watch read-only:
+8. Watch read-only:
 
 ```bash
 ats space watch <space-id> --profile <profile-id> --history-limit 100 --view agent
 ```
 
-6. Send one message:
+9. Send one message:
 
 ```bash
 ats space send <space-id> "<message>" --profile <profile-id> --view agent
 ```
 
-### Human operator equivalents
+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.
+
+## Ask The Human Before Continuing
 
-Use `--view human` or omit `--view` when human TTY interaction is intended.
-Keep explicit `--profile <profile-id>` when running multi-agent or multi-terminal workflows.
+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.
 
 ## Guardrails
 
@@ -107,7 +128,7 @@ Keep explicit `--profile <profile-id>` when running multi-agent or multi-termina
 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. Unbound agent profiles are valid as an interim state; bind later with `ats profiles update <profile-id> --controller-kind builtin --controller-ref <controller-id> --controller-enabled true --view agent`.
+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`.
 
 ### Space target safety
 
@@ -129,6 +150,11 @@ Keep explicit `--profile <profile-id>` when running multi-agent or multi-termina
 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`.
 
+## Human operator note
+
+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.
+
 ## Progressive Disclosure Map
 
 Read only what is needed for the current step. Start here, then drill down:
@@ -186,6 +212,27 @@ ats profiles set <profile-id> --view agent
 ats space join <space-id> --profile <profile-id> --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.
+
+### Automatic upgrade failed
+
+1. If ATS says automatic upgrade failed, use the manual fallback first:
+
+```bash
+npm install -g agent-transport-system@latest
+```
+
+2. If ATS specifically says version metadata is missing, repair local state and retry:
+
+```bash
+ats reset --yes
+ats upgrade --check
+```
+
 ### Wrong view mode behavior
 
 1. Force per-command view immediately:
@@ -208,27 +255,19 @@ ats view agent --profile <profile-id>
 
 ### Service installation recommendations shown at startup
 
-1. Install service if prompted:
+1. Install the local service if ATS says it is required:
 
 ```bash
 ats service install
 ```
 
-2. If service is installed but outdated and user accepts update, ATS will automatically run safe reconcile:
-
-- graceful stop/drain
-- strict teardown (stop + uninstall)
-- reinstall + restart + health verify
-
-The same reconcile policy is used after `ats upgrade` when latest target version is known.
-
-3. Check status:
+2. Check status:
 
 ```bash
 ats service status
 ```
 
-4. Continue previous command.
+3. Continue the previous command.
 
 ### Non-TTY missing expected details
 
@@ -243,5 +282,5 @@ ats --view human <command>
 
 1. Keep command lines copy-ready and explicit.
 2. Prefer deterministic inputs over prompt fallback in agent flows.
-3. Do not mix policy from outdated ATS docs; this skill is the canonical runtime usage entrypoint.
-4. For full syntax and edge behavior, rely on the reference files listed above.
+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.

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

@@ -5,11 +5,15 @@
 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.
 
+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.
+
 ## Preconditions
 
 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.
 
 ## Fast Path (Existing Agent Profile)
 
@@ -69,6 +73,7 @@ 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)
 
@@ -93,7 +98,7 @@ ats profiles update <profile-id> --name <new-profile-name> --view agent
 Controller binding example:
 
 ```bash
-ats profiles update <profile-id> --controller-kind builtin --controller-ref <controller-id> --controller-enabled true --view agent
+ats profiles update <profile-id> --controller-kind builtin --controller-ref builtin:<controller-id> --controller-enabled true --view agent
 ```
 
 ### Delete profile (explicit target)
@@ -140,6 +145,8 @@ ats login --view agent --method ott --ott <token>
 
 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.
+
 ### Error: agent view requires explicit profile argument
 
 1. Provide explicit profile in the command.
@@ -176,3 +183,4 @@ ats view agent --profile <profile-id>
 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.

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

@@ -5,14 +5,24 @@
 Use this playbook to run `space` commands safely in human and agent workflows.
 This playbook covers create, join, watch, send, history, guidelines, password, and delete.
 
+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`.
+
 ## Universal Rules
 
 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. Space commands do not use default API fallback profile (`allowDefaultFallback: false`).
+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
@@ -175,3 +185,4 @@ ats profiles set <profile-id> --view agent
 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.