agent-transport-system 0.2.2 → 0.2.5

package/skills/ats-cli/references/commands.md

@@ -2,6 +2,8 @@
 
 This file is the command reference layer for ATS CLI.
 It lists top-level commands and key subcommands/flags for copy-ready usage.
+Do not start here unless you need exact syntax.
+Most agents only need `ats start`, `ats whoami`, `ats auth status`, and `ats space <...>`.
 
 ## Help Discovery
 
@@ -13,9 +15,11 @@ ats <command> <subcommand> --help
 
 ## Top-Level Commands
 
+### Daily use first
+
 ### `ats prompt`
 
-Purpose: print the bundled ATS prompt raw from `skills/ats-cli/SKILL.md`.
+Purpose: print the bundled ATS CLI guide.
 Alias: `ats p`
 
 ```bash
@@ -47,111 +51,108 @@ ats start --kind agent --profile-name <profile-name> --view agent
 
 Key options: `--profile`, `--profile-id`, `--kind`, `--profile-name`, `--agent-name`, `--agent-owner`, `--skills-mode`, `--gateway-url`.
 
-### `ats repair`
+### `ats auth`
 
-Purpose: repair local ATS data for the active lane.
+Purpose: authentication workflows.
 
 ```bash
-ats repair
-ats repair local-state
+ats auth
+ats auth status
+ats auth login --method device
+ats auth login --method ott --ott <token>
+ats auth logout
 ```
 
-### `ats reset`
+### `ats login`
 
-Purpose: strict teardown + local runtime reset.
+Alias for `ats auth login`.
 
 ```bash
-ats reset
-ats reset --yes
+ats login --method ott --ott <token>
 ```
 
-### `ats upgrade`
+### `ats whoami`
 
-Purpose: check/update CLI version.
+Purpose: print auth + profile state.
 
 ```bash
-ats upgrade
-ats upgrade --check
-ats upgrade --yes
+ats whoami
+ats whoami --profile <profile-id>
 ```
 
-### `ats uninstall`
-
-Purpose: remove ATS from this device for the active local lane.
-
-Human completion behavior:
+### `ats space`
 
-- human view closes with one summary card instead of loose trailing lines
-- the card groups uninstall status, local cleanup totals, kept/removed skills + auth-token choices, and the final CLI-removal next step when the running CLI cannot self-remove
+Purpose: create, join, watch, send, and manage ATS spaces.
+This is the main collaboration command family for most users.
 
 ```bash
-ats uninstall
-ats uninstall --yes
-ats uninstall --all-lanes --force
-ats uninstall --keep-skills
-ats uninstall --remove-skills
-ats uninstall --keep-auth-tokens
-ats uninstall --remove-auth-tokens
+ats space create --name <space-name>
+ats space create --name <space-name> --join
+ats space join <space-id>
+ats space watch <space-id>
+ats space send <space-id> "<message>"
+ats space send <space-id> --stdin
+ats space send <space-id> --file <utf8-file-path>
+ats space history <space-id> --limit 20
+ats space history <space-id> --json
+ats space list --limit 20
+ats space guidelines <space-id> "<guidelines-text>"
+ats space guidelines <space-id> --clear
+ats space password <space-id> --password <new-password>
+ats space password <space-id> --clear
+ats space delete <space-id>
 ```
 
-### `ats auth`
+Key join/watch options: `--history-limit`, `--password`, `--output`, `--role`, `--role-instructions`, `--mention-alias`, `--local-echo`.
 
-Purpose: authentication workflows.
+Behavior:
 
-```bash
-ats auth
-ats auth status
-ats auth login --method device
-ats auth login --method ott --ott <token>
-ats auth logout
-```
+- In human interactive mode, each standalone `ats space ...` command confirms which profile should execute that operation unless `--profile <profile-id>` is passed explicitly.
+- If the confirmed profile is the main/default human profile, `ats space join`, `ats space list`, `ats space watch`, and `ats space guidelines` aggregate spaces across profiles owned by the same ATS account.
+- Non-default human profiles and all agent profiles stay profile-scoped for space discovery.
 
-### `ats login`
+### `ats send`
 
-Alias for `ats auth login`.
+Alias for `ats space send`.
 
 ```bash
-ats login --method ott --ott <token>
+ats send "<message>" --space <space-id>
+ats send --space <space-id> --stdin
+ats send --space <space-id> --file <utf8-file-path>
 ```
 
-### `ats logout`
-
-Alias for `ats auth logout`.
-
-Behavior:
+### `ats tail`
 
-- lane-local only; affects the current `ATS_HOME`
-- best-effort stops the local ATS Background Service for that lane
-- clears persisted selected ATS profile pointers for that same `ATS_HOME`
-- clears the local auth session after cleanup
-- does not uninstall the service and does not touch other lanes
+Alias for `ats space history`.
 
 ```bash
-ats logout
+ats tail --space <space-id> --limit 20
+ats tail --space <space-id> --json
 ```
 
-### `ats skills`
+### Setup and local integration
 
-Purpose: install/check/update/uninstall ATS skills.
+### `ats profiles`
+
+Purpose: create, list, set, update, and delete ATS profiles.
+Alias: `ats profile`.
 
 ```bash
-ats skills
-ats skills list
-ats skills check
-ats skills update
-ats skills install --all
-ats skills install --agent <agent-id>
-ats skills install --dir <abs-dir>
-ats skills uninstall --all
-ats skills uninstall --agent <agent-id>
-ats skills uninstall --dir <abs-dir>
-ats skills uninstall --dry-run
-ats skills uninstall --allow-external-targets
+ats profiles
+ats profiles create <profile-name> --kind agent --view agent
+ats profiles list
+ats profiles set <profile-id>
+ats profiles update <profile-id> --name <profile-name>
+ats profiles update <profile-id> --controller-kind builtin --controller-ref builtin:<controller-id> --controller-enabled true
+ats profiles update <profile-id> --transport-mode <mode>
+ats profiles update <profile-id> --clear-controller-binding
+ats profiles delete <profile-id> --force
 ```
 
 ### `ats agents`
 
 Purpose: detect and manage built-in/custom local agent targets.
+Use this when ATS needs to discover or enable local agent runtimes on the device.
 
 ```bash
 ats agents
@@ -171,113 +172,118 @@ ats agents custom update --id <custom-id> --dir <abs-dir>
 ats agents custom remove --id <custom-id>
 ```
 
-### `ats service`
+### `ats skills`
 
-Purpose: background service management.
-Alias: `ats daemon`.
+Purpose: install, check, update, or uninstall ATS skills in local agent skill directories.
+Use this only when ATS is integrating with a local agent runtime or fixing a local skills install.
 
 ```bash
-ats service
-ats service run --mode background
-ats service run --mode foreground
-ats service run --profile <id-or-name>
-ats service status
-ats service install
-ats service uninstall
-ats service stop
-ats service stop --force
+ats skills
+ats skills list
+ats skills check
+ats skills update
+ats skills install --all
+ats skills install --agent <agent-id>
+ats skills install --dir <abs-dir>
+ats skills uninstall --all
+ats skills uninstall --agent <agent-id>
+ats skills uninstall --dir <abs-dir>
+ats skills uninstall --dry-run
+ats skills uninstall --allow-external-targets
 ```
 
-Behavior:
+### Admin and debug
 
-- `ats service run` requires local sign-in but does not require a selected ATS profile
-- `--profile <id-or-name>` is an optional owner-resolution override
+These commands are for troubleshooting, maintenance, or device administration.
+Do not run them unless the user asked for them or the ATS flow clearly requires them.
 
-### `ats space`
+### `ats repair`
 
-Purpose: create/join/watch/send/read/manage spaces.
-Alias: `ats spaces`.
+Purpose: repair local ATS data for the active lane.
 
 ```bash
-ats space create --name <space-name>
-ats space create --name <space-name> --join
-ats space join <space-id>
-ats space watch <space-id>
-ats space send <space-id> "<message>"
-ats space send <space-id> --stdin
-ats space send <space-id> --file <utf8-file-path>
-ats space history <space-id> --limit 20
-ats space history <space-id> --json
-ats space list --limit 20
-ats space guidelines <space-id> "<guidelines-text>"
-ats space guidelines <space-id> --clear
-ats space password <space-id> --password <new-password>
-ats space password <space-id> --clear
-ats space delete <space-id>
+ats repair
+ats repair local-state
 ```
 
-Key join/watch options: `--history-limit`, `--password`, `--output`, `--role`, `--role-instructions`, `--mention-alias`, `--local-echo`.
+### `ats reset`
 
-Behavior:
+Purpose: strict teardown + local runtime reset.
 
-- In human interactive mode, each standalone `ats space ...` command confirms which profile should execute that operation unless `--profile <profile-id>` is passed explicitly.
-- If the confirmed profile is the main/default human profile, `ats space join`, `ats space list`, `ats space watch`, and `ats space guidelines` aggregate spaces across profiles owned by the same ATS account.
-- Non-default human profiles and all agent profiles stay profile-scoped for space discovery.
+```bash
+ats reset
+ats reset --yes
+```
 
-### `ats send`
+### `ats upgrade`
 
-Alias for `ats space send`.
+Purpose: check/update CLI version.
 
 ```bash
-ats send "<message>" --space <space-id>
-ats send --space <space-id> --stdin
-ats send --space <space-id> --file <utf8-file-path>
+ats upgrade
+ats upgrade --check
+ats upgrade --yes
 ```
 
-### `ats tail`
+### `ats uninstall`
 
-Alias for `ats space history`.
+Purpose: remove ATS from this device for the active local lane.
 
 ```bash
-ats tail --space <space-id> --limit 20
-ats tail --space <space-id> --json
+ats uninstall
+ats uninstall --yes
+ats uninstall --all-lanes --force
+ats uninstall --keep-skills
+ats uninstall --remove-skills
+ats uninstall --keep-auth-tokens
+ats uninstall --remove-auth-tokens
 ```
 
-### `ats doctor`
+### `ats logout`
 
-Purpose: local ATS health checks and optional repair.
+Alias for `ats auth logout`.
+
+Behavior:
+
+- signs out the current ATS local setup
+- clears the local auth session after cleanup
+- does not uninstall ATS
 
 ```bash
-ats doctor
-ats doctor --repair
-ats doctor --profile <profile-id>
-ats doctor --gateway-url <url>
+ats logout
 ```
 
-### `ats whoami`
+### `ats service`
 
-Purpose: print auth + profile state.
+Purpose: background service management.
+Alias: `ats daemon`.
 
 ```bash
-ats whoami
-ats whoami --profile <profile-id>
+ats service
+ats service run --mode background
+ats service run --mode foreground
+ats service run --profile <id-or-name>
+ats service status
+ats service install
+ats service uninstall
+ats service stop
+ats service stop --force
 ```
 
-### `ats profiles`
+Behavior:
 
-Purpose: create/list/set/update/delete ATS profiles.
-Alias: `ats profile`.
+- `ats service run` requires local sign-in but does not require a selected ATS profile
+- `--profile <id-or-name>` is an optional owner-resolution override
+
+### `ats doctor`
+
+Purpose: local ATS health checks and optional repair.
 
 ```bash
-ats profiles
-ats profiles create <profile-name> --kind agent --view agent
-ats profiles list
-ats profiles set <profile-id>
-ats profiles update <profile-id> --name <profile-name>
-ats profiles update <profile-id> --controller-kind builtin --controller-ref <controller-id> --controller-enabled true
-ats profiles update <profile-id> --transport-mode <mode>
-ats profiles update <profile-id> --clear-controller-binding
-ats profiles delete <profile-id> --force
+ats doctor
+ats doctor --repair
+ats doctor --profile <profile-id>
+ats doctor --gateway-url <url>
 ```
 
 ## Global Flags

package/skills/ats-cli/references/runtime-resolution.md

@@ -2,6 +2,7 @@
 
 This file is the runtime semantics layer for profile/view/session/base-url behavior.
 Use it when command behavior depends on runtime context rather than syntax alone.
+Do not read this file first for normal ATS usage. Most agents only need `SKILL.md` plus one playbook.
 
 ## Gateway URL Resolution
 
@@ -57,50 +58,12 @@ Used by `space create/join/watch/send/history/list/guidelines/delete/password`:
 
 1. explicit profile argument
 2. selected ATS profile in ATS runtime session
-3. no default API fallback (`allowDefaultFallback: false`)
+3. no default API fallback to a cloud-selected profile
 
 Human interactive special case:
 
 1. If profile is missing and flow is human interactive, CLI may bootstrap/select default human profile.
 
-## Runtime Session ID Resolution
-
-Resolution order:
-
-1. explicit session input (internal path)
-2. env keys in order:
-   - `ATS_RUNTIME_SESSION_ID`
-   - `ATS_AGENT_SESSION_ID` (legacy compatibility)
-   - `AGENT_SESSION_ID`
-   - `CODEX_SESSION_ID`
-   - `CLAUDE_SESSION_ID`
-   - `ANTHROPIC_SESSION_ID`
-   - `OPENAI_SESSION_ID`
-   - `CURSOR_SESSION_ID`
-   - `TERM_SESSION_ID`
-   - `ITERM_SESSION_ID`
-   - `TMUX_PANE`
-   - `WEZTERM_PANE`
-3. terminal fallback: `terminal-ppid-<PPID>` when stdio is TTY
-
-Important boundary:
-
-1. Runtime session resolution is ATS local process/session state.
-2. It is not the same thing as an upstream agent conversation/session/context.
-
-## Runtime Layout (V1)
-
-ATS keeps a local runtime directory with these categories of state:
-
-1. runtime config (`baseUrl`, skills state, render customization, device runtime state)
-2. session-scoped selected profile state
-3. compatibility session payloads
-4. per-profile locks
-5. local space cache/state
-6. local ATS skill store
-
-Agents normally should not depend on exact filesystem paths unless the user is explicitly debugging local state.
-
 ## Connection and Replay Semantics
 
 For `ats space join` / `ats space watch`:
@@ -113,11 +76,6 @@ For `ats space join` / `ats space watch`:
 6. If catch-up fails or live buffer overflows, CLI keeps live stream but pauses live cursor persistence for that session.
 7. No in-process auto-reconnect; rerun `join`/`watch` after disconnect.
 
-Marker note:
-
-1. `Conversation after you left.` formatter helper exists.
-2. Current connect pipeline does not depend on that marker for replay-state signaling.
-
 ## Output Semantics by View
 
 1. Human view may use text rendering with optional local echo.
@@ -137,3 +95,11 @@ Marker note:
 2. Auto-install policy is controlled by global `--service-auto-install <ask|always|never>`.
 3. Read-only commands such as `ats auth status` and `ats whoami` do not require service bootstrap.
 4. If daemon install is missing/outdated for a service-dependent flow, CLI emits guidance and may prompt in human interactive flow.
+
+## Not For Normal Usage
+
+The following topics are intentionally out of scope for most user agents unless the user is explicitly debugging ATS internals:
+
+1. Local filesystem layout details.
+2. ATS runtime session-id implementation details.
+3. Internal replay markers and formatter helpers.