docs(experimental): rust LSP multiplexer

Author: mareurs

docs/manual/src/experimental/index.md

@@ -6,4 +6,8 @@
 
 ## Available Features
 
-- [Tool Description Diet & Tool Guide Resource](./tool-description-diet.md) — caps tool descriptions at 300 chars, exposes long-form notes via `doc://codescout-tool-guide`.
+- [MCP resources, tool diet, progress notifications](./mcp-resources.md) — token-efficient resource sharing, short descriptions with on-demand guides, and progress notifications for long operations.
+- [Project hints in `activate_project`](./project-hints.md) — manifest-derived primary language, entry points, and build commands surfaced in the activation response so agents have context without running onboarding.
+- [Rust LSP multiplexer](./mux-rust.md) — share a single `rust-analyzer` process across multiple `codescout` instances on the same project, eliminating stale-hover / stale-goto bugs.
+- [Tool usage doctor](./tool-usage-doctor.md) — `doctor://tool-usage` MCP resource reporting per-tool call counts, error/overflow rates, and prune candidates for the next prompt-surface review.
+- [Cross-process write serialization](./cross-process-write-serialization.md) — advisory file lock serializes write-tool calls across concurrent codescout instances on the same project; contention returns a recoverable error instead of corrupting files.

docs/manual/src/experimental/mux-rust.md

@@ -0,0 +1,39 @@
+# Rust LSP multiplexer
+
+> ⚠ Experimental — may change without notice.
+
+## What it does
+
+When two `codescout` instances open the same Rust project, they now share a
+single `rust-analyzer` process via the existing LSP multiplexer (first used
+for `kotlin-lsp`). This eliminates the stale-hover / stale-goto bug that
+appeared after a write in instance A was not reflected in instance B.
+
+## Footprint
+
+- One `rust-analyzer` per `(project-root)` across all `codescout` instances
+  on the machine.
+- Idle-shutdown after 180 seconds with no connected clients.
+- Memory saved: one full `rust-analyzer` (2–4 GB on a medium Cargo
+  workspace) per extra `codescout` instance.
+
+## Opt out
+
+Add to `.codescout/project.toml`:
+
+```toml
+[lsp.rust]
+mux = false
+```
+
+Then `/mcp` restart. Codescout will fall back to spawning a dedicated
+`rust-analyzer` per instance, as before.
+
+## Known limits
+
+- Unix only (the mux is `#[cfg(unix)]`).
+- `rust-analyzer` must be on `PATH`.
+- If two clients connect before `rust-analyzer` completes initialization,
+  the second client waits on a 5-retry / 1-second backoff. No-op
+  behaviourally; you may see a brief startup delay under heavy
+  concurrency.