docs(skills): add cross-environment T3 session management

.agents/skills/t3-cross-environment/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: t3-cross-environment
+description: Manage T3 Code sessions across devices and environments. Use to find and inspect remote threads, exchange messages, retrieve replies, and start requested sessions or worktrees through destination MCP or an existing SSH connection.
+---
+
+# T3 cross-environment session management
+
+Use this skill to manage T3 sessions on another device or environment: find
+conversations, inspect their state, exchange messages, read results and start
+new sessions when requested. For example, a Linux host can coordinate work
+in a Mac-hosted conversation. Each environment is a running T3 server with its
+own projects and threads; separate environments can also run on the same device.
+
+T3 tools address the environment serving them. Seeing another environment in
+the client does not make its threads reachable through the current MCP server;
+a local `thread_not_found` does not establish that a remote thread is gone.
+
+## Choose the destination
+
+Identify the destination environment, project and exact thread ID. Keep any
+`mcp:` prefix. Use an available, authorized MCP connection to that destination
+and its current tool schemas. Do not invent an environment-routing parameter.
+
+For another host without a destination MCP connection, use its supported
+`t3 thread` CLI over an existing authorized SSH route, as the account owning
+that T3 environment. Confirm the executable and T3 home, including any custom
+`--base-dir`. Read [CLI and SSH commands](references/cli.md) before using this
+route.
+
+[Outside agents](https://github.com/pingdotgg/t3code/blob/main/docs/user/outside-agents.md)
+describes supported MCP setup. Missing access, authentication or a running
+server is a prerequisite to report; do not extract credentials, hand-build
+tokens, edit the live database directly or restart a service to reach a thread.
+
+## Read, message or start
+
+- Inspect the destination thread's state and recent messages before answering
+  about it or sending. Resolve ambiguous recipients before a mutation. Sending
+  or launching must be authorized by the user's task; reading a reference does
+  not authorize a message.
+- Start a top-level conversation only when a new or separate session was
+  requested. A subagent request uses the host's delegation workflow. CLI-created
+  conversations have no delegated-task lifecycle or automatic parent result
+  delivery.
+- Select the destination project and intended workspace before launch. Use the
+  supported worktree option for independent code work. Its base ref must exist
+  on the destination; local dirty files and caller context do not transfer.
+- CLI launches use destination defaults, not the caller's settings. Preserve
+  requested provider, model, options and permission limits. If the destination
+  interface cannot represent or verify them, report the gap before launch.
+  Host access does not override the calling session's restrictions.
+
+## Receive and continue
+
+Retain the destination, thread/run IDs and observed status. Use the returned
+thread link when available. Acceptance is not completion: inspect the result
+for the requested run, including failed or waiting-for-input states.
+
+After an uncertain send or launch, inspect the destination before retrying.
+The CLI exposes no retry key. If you cannot establish whether it succeeded,
+report the uncertainty instead of duplicating work.
+
+Before following up, inspect the latest messages and respect a user's takeover
+or stop request. Stopping automatic messages does not stop a running agent;
+use an available, authorized stop control if that is what the user requested.

.agents/skills/t3-cross-environment/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "T3 Cross-Environment Management"
+  short_description: "Manage T3 sessions across devices and environments"
+  default_prompt: "Use $t3-cross-environment to manage the requested T3 sessions on another device or environment."

.agents/skills/t3-cross-environment/references/cli.md

@@ -0,0 +1,107 @@
+# T3 CLI across environments
+
+These examples use SSH to run the CLI on the destination device, where the
+session lives or will be started. If already executing on that device, omit
+the SSH wrapper. Replace `T3_HOST` with an existing SSH destination for the
+account owning T3, and replace the executable, T3 home, project path and IDs
+with checked destination values. Shell-quote replacement arguments for the
+destination shell; the examples use POSIX shells.
+
+Use the installed launcher for that environment. Desktop installations provide
+`~/.t3/bin/t3`; another `t3` on a noninteractive PATH may belong to a different
+installation. Keep `--base-dir` consistent on every command. It names the T3
+home, not its `userdata` subdirectory or the project directory.
+
+## Discover and inspect
+
+Check the destination's installed capabilities before choosing commands or flags:
+
+```sh
+ssh -o BatchMode=yes T3_HOST '"/absolute/path/to/t3" thread --help'
+ssh -o BatchMode=yes T3_HOST '"/absolute/path/to/t3" thread start --help'
+ssh -o BatchMode=yes T3_HOST '"/absolute/path/to/t3" thread list --base-dir "/absolute/path/to/t3-home" --json --project "/absolute/path/to/project"'
+ssh -o BatchMode=yes T3_HOST '"/absolute/path/to/t3" thread show --base-dir "/absolute/path/to/t3-home" --json --messages 4 "THREAD_ID"'
+```
+
+The project must already be registered on that environment. A project ID or a
+path inside the project works. Use the exact thread ID from the destination,
+including any `mcp:` prefix. `show --json` includes thread state and recent
+messages; inspect its workspace, model and modes as relevant to the task.
+
+## Send and retrieve the reply
+
+Pass literal message text through stdin. A quoted heredoc keeps shell syntax in
+the prompt from being evaluated by the sending shell:
+
+```sh
+ssh -o BatchMode=yes T3_HOST '"/absolute/path/to/t3" thread send --base-dir "/absolute/path/to/t3-home" --json "THREAD_ID" -' <<'T3_MESSAGE'
+Request REQUEST_ID from SOURCE_SESSION: please report the current result of TASK.
+Reply in this conversation.
+T3_MESSAGE
+```
+
+Replace the example message with the authorized request and a recognizable
+correlation label. Retain the returned thread/run IDs. CLI `send` queues a new
+turn behind a busy one; it does not steer or interrupt it.
+
+Read the result from the same destination:
+
+```sh
+ssh -o BatchMode=yes T3_HOST '"/absolute/path/to/t3" thread show --base-dir "/absolute/path/to/t3-home" --json --messages 4 "THREAD_ID"'
+```
+
+Match message `runId` values to the request, rather than assuming the latest
+assistant message answers it. Increase `--messages` if another turn has since
+run. For efficient paged history or richer run inspection, use destination MCP
+tools when available; `--messages` limits printed output, not history retrieval.
+
+When sending or starting, add `--wait` if you want that command to wait for its
+run and print the reply. Use an interruptible execution session for long waits.
+For a returned run result, exit 1 means it failed or stopped; exit 2 means it
+needs an answer in the app. Command, transport and result-retrieval errors also
+fail the command, so exit 1 alone does not prove the run failed. Inspect stderr
+and any JSON status, IDs, reply and error; reconcile an unknown outcome before
+retrying. Text-mode `start --wait` prints the thread ID to stderr before waiting;
+text-mode `send --wait` prints no IDs. With `--json`, `threadId` and `runId` are
+printed only in the final result, so a disconnected JSON wait can leave no run
+ID or final result. Without `--wait`, acceptance returns promptly and results
+can be read later; it does not create an automatic completion callback.
+
+## Start a requested conversation
+
+Choose a destination project and give it a recognizable title and task label.
+For independent code work, let T3 create and bind a worktree before the agent
+starts:
+
+```sh
+ssh -o BatchMode=yes T3_HOST '"/absolute/path/to/t3" thread start --base-dir "/absolute/path/to/t3-home" --json --title "Requested task REQUEST_ID" --worktree "BASE_REF" --branch "NEW_BRANCH" --provider "PROVIDER_INSTANCE" --model "MODEL_SLUG" "/absolute/path/to/project" -' <<'T3_TASK'
+Request REQUEST_ID from SOURCE_SESSION.
+Task: DESCRIBE_REQUESTED_WORK
+Scope and allowed actions: DESCRIBE_BOUNDARIES
+Acceptance and reply: DESCRIBE_EXPECTED_RESULT
+T3_TASK
+```
+
+Replace the example brief and every symbolic argument with the actual request
+and checked destination values. `--provider` and `--model` go together and
+replace the entire model selection; they do not inherit saved model options.
+To retain project options, verify the complete destination default selection
+and omit both flags. If the requested selection cannot be expressed by the CLI,
+use an authorized destination MCP interface or report the gap before launch.
+Omit `--worktree` and `--branch` when sharing the project folder is intended.
+`--branch` requires `--worktree`, and the base ref and committed inputs must
+exist remotely.
+
+Read the new thread with `show --json` to confirm its workspace, model and modes
+and obtain its link. It does not expose model options such as reasoning effort;
+verify required options through supported project/configuration controls before
+launch. The CLI's `start --json` result contains IDs, not a link.
+Current CLI help does not expose model-option or permission-mode flags, or a
+stop command. Check installed help for changes; do not invent flags or silently
+drop requested settings. Use verified suitable defaults or an authorized
+destination MCP interface when those controls are needed.
+
+If SSH disconnects or a response is lost, reconcile `list` and `show` using
+the title, request label and messages before repeating a mutation. Neither
+`start` nor `send` exposes an idempotency flag. A reverse message needs its own
+authorized destination connection; otherwise read the reply where it was sent.