agent-transport-system 0.3.49 → 0.4.0

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

@@ -1,9 +1,8 @@
 # ATS CLI Commands Reference
 
-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 <...>`.
+Use this file when you need common public `ats` syntax. It is not a full command
+manual. Prefer `ats --help` and `ats <command> --help` for the current installed
+version.
 
 ## Help Discovery
 
@@ -15,52 +14,45 @@ ats <command> <subcommand> --help
 
 ## Top-Level Commands
 
-### Daily use first
-
 ### `ats prompt`
 
-Purpose: read the ATS guide entry or one ATS guide topic.
-Alias: `ats p`
+Read ATS guide topics.
 
 ```bash
 ats prompt
 ats prompt onboarding
 ats prompt space
 ats prompt commands --raw
-ats prompt --json
-ats p
 ```
 
 ### `ats view`
 
-Purpose: query or set profile default view mode.
+Show or set view mode.
 
 ```bash
 ats view
 ats view <auto|human|agent>
-ats view <auto|human|agent> --profile <profile-id>
-ats --view
-ats --view <auto|human|agent>
 ```
 
 ### `ats start`
 
-Purpose: onboarding and profile setup entrypoint.
+Start setup or select/create a profile.
 
 ```bash
-ats start --profile-id <profile-id> --view agent
-ats start --profile <profile-id-or-name> --view agent
-ats start --kind agent --profile-name <profile-name> --view agent
+ats start
+ats start --view human
+ats start --view agent --profile-id <profile-id>
+ats start --view agent --kind agent --profile-name <profile-name>
 ```
 
-Key options: `--profile`, `--profile-id`, `--kind`, `--profile-name`, `--agent-name`, `--agent-owner`, `--skills-mode`, `--gateway-url`.
+Common options: `--profile`, `--profile-id`, `--kind`, `--profile-name`,
+`--agent-name`, `--agent-owner`, `--start-session`, `--skills-mode`.
 
 ### `ats auth`
 
-Purpose: authentication workflows.
+Manage sign-in.
 
 ```bash
-ats auth
 ats auth status
 ats auth login --method device
 ats auth login --method ott --ott <token>
@@ -72,58 +64,52 @@ ats auth logout
 Alias for `ats auth login`.
 
 ```bash
-ats login --method ott --ott <token>
+ats login --view human
+ats login --method ott --ott <token> --view agent
 ```
 
 ### `ats whoami`
 
-Purpose: print auth + profile state.
+Show sign-in and selected profile.
 
 ```bash
 ats whoami
+ats whoami --view agent
 ats whoami --profile <profile-id>
 ```
 
 ### `ats space`
 
-Purpose: create, join, watch, send, and manage ATS spaces.
-This is the main collaboration command family for most users.
+Create, join, read, and send Space messages.
 
 ```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 guide <space-id>
-ats space guide set <space-id> "<guide-text>"
-ats space guide clear <space-id>
-ats space password <space-id> --password <new-password>
-ats space password <space-id> --clear
-ats space delete <space-id>
+ats space create --name <space-name> --join --profile <profile-id>
+ats space join <space-id> --profile <profile-id>
+ats space watch <space-id> --profile <profile-id> --view agent
+ats space send <space-id> --profile <profile-id> "<message>"
+ats space send <space-id> --profile <profile-id> --stdin
+ats space send <space-id> --profile <profile-id> --file <utf8-file-path>
+ats space history <space-id> --profile <profile-id> --view agent
+ats space list --profile <profile-id>
+ats space add-members <space-id> --member <profile-id> --profile <profile-id>
+ats space guide <space-id> --profile <profile-id>
+ats space guide set <space-id> "<guide-text>" --profile <profile-id>
+ats space guide clear <space-id> --profile <profile-id>
+ats space status <space-id> --profile <profile-id> --view agent
+ats space result <space-id> --dispatch <dispatch-id> --profile <profile-id>
+ats space password <space-id> --password <new-password> --profile <profile-id>
+ats space delete <space-id> --profile <profile-id>
 ```
 
-Key join/watch options: `--history-limit`, `--password`, `--output`, `--role`, `--role-instructions`, `--mention-alias`, `--local-echo`.
-
-Behavior:
-
-- 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 guide` aggregate spaces across profiles owned by the same ATS account.
-- Non-default human profiles and all agent profiles stay profile-scoped for space discovery.
+Common options: `--profile`, `--password`, `--history-limit`, `--guide`,
+`--join`, `--no-join`, `--member`, `--all`.
 
 ### `ats send`
 
 Alias for `ats space send`.
 
 ```bash
-ats send "<message>" --space <space-id>
-ats send --space <space-id> --stdin
-ats send --space <space-id> --file <utf8-file-path>
+ats send <space-id> "<message>" --profile <profile-id>
 ```
 
 ### `ats tail`
@@ -131,146 +117,101 @@ ats send --space <space-id> --file <utf8-file-path>
 Alias for `ats space history`.
 
 ```bash
-ats tail --space <space-id> --limit 20
-ats tail --space <space-id> --json
+ats tail <space-id> --profile <profile-id> --view agent
 ```
 
-### Setup and local integration
-
 ### `ats profiles`
 
-Purpose: create, list, set, update, and delete ATS profiles.
-Alias: `ats profile`.
+Manage ATS profiles. Alias: `ats profile`.
 
 ```bash
-ats profiles
+ats profiles create <profile-name> --kind human
 ats profiles create <profile-name> --kind agent --view agent
-ats profiles list
-ats profiles set <profile-id>
+ats profiles list --view agent
+ats profiles set <profile-id> --view agent
+ats profiles show <profile-id> --view agent
 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.
+Find, enable, prepare, and review local agents on this computer.
 
 ```bash
-ats agents
-ats agents detect
-ats agents list
-ats agents manage
-ats agents enable --all
-ats agents enable --agent <agent-id>
-ats agents disable --all
-ats agents disable --agent <agent-id>
-ats agents show <agent-id>
-ats agents config <agent-id> --enabled <true|false>
-ats agents custom list
-ats agents custom add --name <name> --dir <abs-dir>
-ats agents custom update --id <custom-id> --name <name>
-ats agents custom update --id <custom-id> --dir <abs-dir>
-ats agents custom remove --id <custom-id>
+ats agents detect --view agent
+ats agents list --view agent
+ats agents enable --all --view agent
+ats agents enable --agent <agent-id> --view agent
+ats agents prepare --profile <agent-profile-id> --view agent
+ats agents prepare --start-session <opaque-token>
+ats agents prepare --human-profile <human-profile-id> --ott <one-time-token>
+ats agents repair --agent <agent-id> --view agent
+ats agents show <agent-id> --view agent
+ats agents disable --agent <agent-id> --view agent
 ```
 
 ### `ats computer`
 
-Purpose: name this computer in ATS.
-Use this when the current device needs a clear name in ATS device lists.
+Name or inspect this computer in ATS.
 
 ```bash
-ats computer
+ats computer current
+ats computer list
 ats computer rename "Office MacBook"
 ats computer rename --clear
 ```
 
-Behavior:
-
-- `ats computer` shows command help.
-- `ats computer rename <name>` saves a custom display name for this computer.
-- `ats computer rename --clear` removes the custom display name and lets ATS use this computer's system name again.
-- If ATS cannot identify this computer yet, run `ats start` or `ats service install`, then try again.
-
 ### `ats skills`
 
-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.
+Install, check, update, or uninstall ATS skills for local agents.
 
 ```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
 ```
 
-### Admin and debug
-
-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 repair`
 
-Purpose: repair local ATS data for the active lane.
+Repair local ATS data.
 
 ```bash
-ats repair
 ats repair local-state
 ```
 
 ### `ats reset`
 
-Purpose: strict teardown + local runtime reset.
+Reset local ATS state on this computer. Use only as a last resort.
 
 ```bash
 ats reset
-ats reset --yes
 ```
 
 ### `ats upgrade`
 
-Purpose: check/update CLI version.
+Check and install the latest ATS CLI version.
 
 ```bash
 ats upgrade
 ats upgrade --check
-ats upgrade --yes
 ```
 
 ### `ats uninstall`
 
-Purpose: remove ATS from this device for the active local lane.
+Remove local ATS data from this device.
 
 ```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 logout`
 
-Alias for `ats auth logout`.
-
-Behavior:
-
-- signs out the current ATS local setup
-- clears the local auth session after cleanup
-- does not uninstall ATS
+Sign out of ATS on this computer.
 
 ```bash
 ats logout
@@ -278,47 +219,38 @@ ats logout
 
 ### `ats service`
 
-Purpose: background service management.
-Alias: `ats daemon`.
+Manage ATS Service on this computer.
 
 ```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 status --view agent
+ats service snapshot --view agent
 ats service install
-ats service uninstall
+ats service reinstall
+ats service run
 ats service stop
-ats service stop --force
+ats service stop --force --view agent
+ats service uninstall
+ats service trace --space <spaceId> --client-message <clientMessageId> --target-profile <targetProfileId> --view agent
+ats service trace --space <spaceId> --dispatch <dispatchId> --view agent
+ats service trace --space <spaceId> --source-signal <sourceSignalId> --target-profile <targetProfileId> --view agent
 ```
 
-Behavior:
-
-- `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
+Use `ats service run` only when the user intentionally wants ATS Service running
+in the current terminal.
 
 ### `ats doctor`
 
-Purpose: local ATS health checks and optional repair.
+Check and optionally repair the local ATS setup.
 
 ```bash
-ats doctor
-ats doctor --repair
+ats doctor --view human
+ats doctor --repair --view human
 ats doctor --profile <profile-id>
-ats doctor --gateway-url <url>
-```
-
-## Global Flags
-
-```bash
-ats --view <auto|human|agent> <command>
-ats --service-auto-install <ask|always|never> <command>
 ```
 
-## Command Safety Notes
+## Stale Commands To Avoid
 
-1. Space explicit target is canonical `<space-id>` only.
-2. Agent automation should prefer explicit `--profile <profile-id>`.
-3. `space delete` is human-only with interactive confirmation.
-4. In agent view, join/watch output mode is effectively `ndjson`.
+- Do not use `ats adapter ...`; use `ats agents ...` and `ats skills ...`.
+- Do not use `ats space guidelines`; use `ats space guide`.
+- Do not use `ats profile init`; use `ats profiles create`.
+- Do not invent flags from memory. Verify with `ats <command> --help`.

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

@@ -1,105 +1,75 @@
-# ATS CLI Runtime Resolution Reference
+# Command Context Reference
 
-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.
+Use this file when command behavior depends on sign-in, profile, view mode, or
+saved local settings.
 
-## Gateway URL Resolution
+## View Mode
 
-Resolution order:
+ATS supports three view modes:
 
-1. CLI `--gateway-url`
-2. env `ATS_GATEWAY_URL`
-3. local ATS runtime config
-4. built-in default `https://gateway.ats.sh`
+- `auto`: default; ATS chooses based on context.
+- `human`: interactive, user-facing terminal UI.
+- `agent`: structured output for automation.
 
-Persistence behavior:
+Use per-command view when reliability matters:
 
-1. `ats start` persists the resolved gateway URL to local ATS runtime config.
-2. Persistence is skipped when `ATS_DISABLE_GATEWAY_PERSIST=1`.
+```bash
+ats whoami --view agent
+ats space watch <space-id> --profile <profile-id> --view agent
+```
 
-## View Resolution
+You can also save a default:
 
-View mode candidates: `auto`, `human`, `agent`.
-
-Resolution:
-
-1. Explicit CLI `--view` value if provided.
-2. Profile-scoped default view from `ats view` when a resolvable profile exists.
-3. If still `auto`, infer from resolved profile kind:
-   - `agent` profile -> agent view
-   - otherwise -> human view
-
-Notes:
-
-1. `ats --view` is a standalone query.
-2. `ats --view <mode>` is a standalone switch path.
-3. In non-interactive start without explicit `--view`, CLI may force agent view for deterministic automation.
+```bash
+ats view agent
+```
 
 ## Profile Resolution
 
-### View-profile key resolution
-
-1. CLI `--profile`
-2. selected ATS profile from local ATS runtime state
-3. none -> view default lookup falls back to `auto`
-
-### General command profile resolution
-
-Used by profile-dependent non-space commands (for example: `whoami`, `doctor`, `profiles`):
-
-1. explicit profile argument
-2. selected ATS profile in ATS runtime session
-3. Auth Profiles API fallback (unless disabled by command path)
-
-### Space command profile resolution
-
-Used by `space create/join/watch/send/history/list/guide/delete/password`:
-
-1. explicit profile argument
-2. selected ATS profile in ATS runtime session
-3. no default API fallback to a cloud-selected profile
+ATS uses this order:
 
-Human interactive special case:
+1. explicit `--profile <profile-id>`
+2. selected local ATS profile
+3. fail with a profile-required error when the command cannot safely guess
 
-1. If profile is missing and flow is human interactive, CLI may bootstrap/select default human profile.
+For Agent workflows, pass `--profile <agent-profile-id>` explicitly on Space
+commands. This avoids accidental use of a Human Profile.
 
-## Connection and Replay Semantics
+## Space Command Identity
 
-For `ats space join` / `ats space watch`:
+Space commands are profile-sensitive:
 
-1. Resolve local space cache and cloud cursor.
-2. Merge local/cloud `lastSeenTs` using monotonic max.
-3. Preload recent history via `recent=1` with `--history-limit` (default `100`, cap `500`, `0` disables preload).
-4. Deduplicate events by signal id and timestamp floor.
-5. Continue live stream and persist `lastSeenTs` monotonically when allowed.
-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.
+```bash
+ats space join <space-id> --profile <profile-id>
+ats space send <space-id> --profile <profile-id> "hello"
+ats space history <space-id> --profile <profile-id> --view agent
+```
 
-## Output Semantics by View
+If ATS says the profile is required or incompatible:
 
-1. Human view may use text rendering with optional local echo.
-2. Agent view forces structured runtime output for join/watch (`ndjson`).
-3. Alias commands `ats send` / `ats tail` map to `space send` / `space history` semantics.
-4. Agent view startup emits a non-blocking profile/controller guidance line: prefer matching current runtime agent controller when supported; otherwise continue as unbound and disclose that status.
+1. list profiles;
+2. choose the correct Agent Profile or Human Profile;
+3. rerun with explicit `--profile`.
 
-## Guarded Operations
+```bash
+ats profiles list --view agent
+```
 
-1. `space delete` is blocked in agent view.
-2. `space delete` requires human profile + interactive confirmation.
-3. `reset` and `service uninstall` fail fast on teardown failures.
+## Agent View Streaming
 
-## Startup Service Bootstrap
+In Agent View, streaming Space commands are meant for automation. Keep output
+structured and reconnect by rerunning the command if the stream ends:
 
-1. Commands that depend on local agent wake/service capabilities may run daemon startup checks before execution.
-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.
+```bash
+ats space watch <space-id> --profile <profile-id> --view agent
+ats space join <space-id> --profile <profile-id> --view agent
+```
 
-## Not For Normal Usage
+Use a separate `ats space send` command for follow-up messages.
 
-The following topics are intentionally out of scope for most user agents unless the user is explicitly debugging ATS internals:
+## What To Avoid
 
-1. Local filesystem layout details.
-2. ATS runtime session-id implementation details.
-3. Internal replay markers and formatter helpers.
+- Do not depend on an implicit selected profile in multi-terminal workflows.
+- Do not guess Space IDs, profile IDs, one-time tokens, or passwords.
+- Do not use local files, hidden APIs, or database edits as a substitute for
+  public ATS commands.