diff --git a/references/config.md b/references/config.md
index a09d1f39..e709f51b 100644
--- a/references/config.md
+++ b/references/config.md
@@ -334,6 +334,25 @@ Supported types are:
 
 All connection types support an optional `path` suffix to specify a directory to `cd` to before running WP-CLI; `path` is a full system path starting with either `/` or `~`. (If `WP_CLI_SSH_PRE_CMD` is specified, `cd` is run after this pre-command.)
 
+### Using path with SSH
+
+When using SSH connections, you must specify the remote WordPress path as a suffix in the SSH connection string:
+
+```yaml
+# Using the path suffix directly in the ssh parameter
+ssh: user@host~/path/to/wordpress
+```
+
+**Important:** When using `ssh` and `path` as separate top-level options in `wp-cli.yml`, the `path` option will be ignored. Always include the path as a suffix in the SSH connection string (e.g., `ssh: user@host~/path/to/wordpress`).
+
+Note: Within an alias definition, you can specify `ssh` and `path` as separate options:
+
+```yaml
+@staging:
+  ssh: user@host
+  path: /path/to/wordpress
+```
+
 The SSH connection type also supports two advanced connection configuration options, which must be specified via an alias in the YAML configuration:
 
 * `proxyjump` - Specifies a jumpbox connection string, which is passed to `ssh -J`