docs: cover new default ssh domain behavior and function

docs/changelog.md

@@ -25,6 +25,9 @@ As features stabilize some brief notes about them will accumulate here.
 * [pane:activate()](config/lua/pane/activate.md) and [tab:activate()](config/lua/MuxTab/activate.md). #3217
 * [ulimit_nofile](config/lua/config/ulimit_nofile.md) and [ulimint_nproc](config/lua/config/ulimit_nproc.md) options. ?3353
 * [serial_ports](config/lua/config/serial_ports.md) for more convenient access to serial ports
+* `ssh_domains` now auto-populate from your `~/.ssh/config` file. You can use
+  [wezterm.default_ssh_domains()](config/lua/wezterm/default_ssh_domains.md) to
+  obtain that same information and amend/extend it.
 
 #### Fixed
 * mux: Stale remote window mapping could prevent spawning new tabs in remote domain. #2759

docs/config/lua/config/ssh_domains.md

@@ -4,3 +4,15 @@ Configures SSH multiplexing domains.  [Read more about SSH Domains](
 ../../../multiplexing.md#ssh-domains).
 
 This option accepts a list of [SshDomain](../SshDomain.md) objects.
+
+{{since('nightly')}}
+
+If you don't set `ssh_domains` in your config, wezterm will default
+to configuring it as if you had:
+
+```lua
+config.ssh_domains = wezterm.default_ssh_domains()
+```
+
+See also [wezterm.default_ssh_domains()](../wezterm/default_ssh_domains.md).
+

docs/config/lua/wezterm/default_ssh_domains.md

@@ -0,0 +1,28 @@
+# wezterm.default_ssh_domains()
+
+{{since('nightly')}}
+
+Computes a list of [SshDomain](../SshDomain.md) objects based on
+the set of hosts discovered in your `~/.ssh/config`.
+
+Each host will have both a plain SSH and a multiplexing SSH domain
+generated and returned in the list of domains.  The former don't
+require wezterm to be installed on the remote host, while the
+latter do require it.
+
+The intended purpose of this function is to allow you the opportunity
+to edit/adjust the returned information before assigning it to
+your config.
+
+For example, if all of the hosts referenced by your ssh config
+are unix machines, you might want to inform wezterm of that
+so that features like spawning a tab in the same directory
+as an existing tab work even for a plain SSH session:
+
+```lua
+config.ssh_domains = wezterm.default_ssh_domains()
+for _, dom in ipairs(config.ssh_domains) do
+  dom.assume_shell = 'Posix'
+end
+```
+