docs(cli): document the .sock listener rule (#1647)

## Summary

The `--host`/`--port` help text in both binaries and two passages in `docs/python-client.md` still taught the deprecated `--port 0` Unix-socket spelling. Per `src/server/transport.rs` the rule is: a `--host` ending in `.sock` selects a Unix domain socket whatever `--port` says (the b10621 rule), `--port 0` on TCP binds an ephemeral port, and the legacy `--port 0` + path spelling emits a deprecation warning. The four flag doc-comments and both doc examples now describe the `.sock` rule.

## Related issues

Closes #1631

## Type of change

- [ ] `feat` — new user-visible feature
- [ ] `fix` — bug fix
- [ ] `perf` — performance improvement (include before/after numbers in the PR body)
- [ ] `refactor` — internal restructuring without behavior change
- [ ] `chore` — build, CI, dependencies, release infrastructure
- [x] `docs` — documentation only
- [ ] `test` — tests only

Author: agatha197

docs/python-client.md

@@ -70,8 +70,8 @@ Start a matching server with the CLI:
 # TCP
 mlxcel serve -m mlx-community/Qwen3-4B-4bit --host 127.0.0.1 --port 8080
 
-# Unix domain socket: --port 0 reinterprets --host as the socket path
-mlxcel serve -m mlx-community/Qwen3-4B-4bit --host /tmp/mlxcel.sock --port 0
+# Unix domain socket: a --host ending in .sock selects socket mode
+mlxcel serve -m mlx-community/Qwen3-4B-4bit --host /tmp/mlxcel.sock
 ```
 
 Passing both a model and a connect target raises `MlxcelError`, because the mode would be ambiguous.
@@ -90,7 +90,7 @@ with mlxcel.LLM("mlx-community/Qwen3-4B-4bit", socket=str(runtime_dir / "mlxcel.
     print(llm.generate("hello"))
 ```
 
-The CLI equivalent is `mlxcel serve --host "$XDG_RUNTIME_DIR/mlxcel.sock" --port 0`.
+The CLI equivalent is `mlxcel serve --host "$XDG_RUNTIME_DIR/mlxcel.sock"`.
 
 On macOS, `$TMPDIR` already expands to a per-user path under `/var/folders`, so the default socket is private there. On Linux without an active login session, `$XDG_RUNTIME_DIR` may be absent; fall back to a `0700` subdirectory under your home directory if needed.
 

src/bin/mlx_server.rs

@@ -400,11 +400,11 @@ struct ServerArgs {
     #[arg(long = "lora-fuse")]
     lora_fuse: bool,
 
-    /// Host address to bind to (or Unix socket path when --port 0)
+    /// Host address to bind to (a value ending in .sock is served as a Unix domain socket)
     #[arg(long, env = "LLAMA_ARG_HOST", default_value = "127.0.0.1")]
     host: String,
 
-    /// Port number to listen on (0 = Unix socket mode using --host as socket path)
+    /// Port number to listen on (0 = bind an ephemeral port; ignored when --host ends in .sock)
     #[arg(long, env = "LLAMA_ARG_PORT", default_value_t = 8080)]
     port: u16,
 

src/main.rs

@@ -1186,11 +1186,11 @@ pub(crate) struct ServeArgs {
     #[arg(short = 'a', long, env = "LLAMA_ARG_ALIAS", value_name = "NAME")]
     alias: Option<String>,
 
-    /// Host address to bind to (or Unix socket path when --port 0)
+    /// Host address to bind to (a value ending in .sock is served as a Unix domain socket)
     #[arg(long, env = "LLAMA_ARG_HOST", default_value = "127.0.0.1")]
     host: String,
 
-    /// Port number to listen on (0 = Unix socket mode using --host as socket path)
+    /// Port number to listen on (0 = bind an ephemeral port; ignored when --host ends in .sock)
     #[arg(long, env = "LLAMA_ARG_PORT", default_value_t = 8080)]
     port: u16,