docs: cleanup SSH docs

Author: ammario

docs/ssh.md

@@ -1,11 +1,14 @@
 # SSH Workspaces
 
-cmux supports using an SSH remote to run workspaces. When configured, all tool operations will
+cmux supports using remote hosts over SSH for workspaces. When configured, all tool operations will
 execute over SSH and the agent is securely isolated from your local machine.
 
-We highly recommend using SSH workspaces for an optimal agentic experience:
+Our security architecture considers the remote machine potentially hostile. No keys or credentials are implicitly transferred there—just the git archive and [Project Secrets](./project-secrets.md).
+
+We highly recommend using SSH workspaces for an optimal experience:
 
 - **Security**: Prompt injection risk is contained to the credentials / files on the remote machine.
+  - SSH remotes pair nicely with [agentic git identities](./agentic-git-identity.md)
 - **Performance**: Run many, many agents in parallel while maintaining good battery life and UI performance
 
 ![ssh workspaces](./img/new-workspace-ssh.webp)
@@ -15,11 +18,12 @@ The Host can be:
 - a hostname (e.g. `my-server.com`)
 - a username and hostname (e.g. `[email protected]`)
 - an alias from your `~/.ssh/config`, e.g. `my-server`
+- anything that passes through `ssh <host>` can be used as a host
 
-In fact, we delegate SSH configuration to the system's `ssh` command, so can set up advanced
-configuration for your agentic machine in your local `~/.ssh/config` file.
+We delegate SSH configuration to the system's `ssh` command, so you can set up advanced
+configuration for your agent host in your local `~/.ssh/config` file.
 
-Here's an example of an alias:
+Here's an example of a config entry:
 
 ```
 Host ovh-1
@@ -33,9 +37,9 @@ Host ovh-1
 
 There are a few practical ways to set up authentication.
 
-### Local defaults
+### Local default keys
 
-Ensure your private key is one of these locations:
+`ssh` will check these locations by default:
 
 ```
 ~/.ssh/id_rsa
@@ -47,12 +51,14 @@ Ensure your private key is one of these locations:
 
 ### SSH Agent
 
-If you have an SSH agent running, you can use it to authenticate.
+If you have an SSH agent running, you can add your key:
 
 ```
-ssh-add ~/.ssh/id_rsa
+ssh-add ~/.ssh/my_key_ecdsa
 ```
 
+and `ssh` will use it to authenticate.
+
 ### Config
 
 You can also configure authentication in your `~/.ssh/config` file.
@@ -66,12 +72,10 @@ Host my-server
 
 ## Coder Workspaces
 
-If you're using [Coder Workspaces](https://coder.com/docs), you can leverage your existing Workspace
-with cmux:
+If you're using [Coder Workspaces](https://coder.com/docs), you can use an existing Workspace
+as a cmux agent host:
 
 1. Run `coder config-ssh`
 2. Use `coder.<workspace-name>` as your SSH host when creating a new cmux workspace
 
-Note that in this approach we're multiplexing agents onto a single Coder Workspace, not creating
-a new workspace per agent. This avoids the workspace creation overhead for rapid muxing,
-while still isolating the agent from your local machine.
+Note that in this approach we're multiplexing cmux workspaces onto a single Coder workspace. This avoids the compute provisioning overhead to enable rapid creation and deletion of workspaces.