docs: Document Last Focused Wins telemetry architecture for Neovim

README.md

@@ -84,16 +84,28 @@ You can also programmatically query these live metrics via the API endpoint:
 For a deep dive into the architecture, Write-Ahead Logging (WAL), locking mechanisms, and the HTTP SSE event loop, consult the design.md file in this repository.
 
 ## Neovim Integration
-The `linux-nvim` and `win-nvim` MCP servers provide direct Msgpack-RPC communication with Neovim.
+The linux-nvim and win-nvim MCP servers provide direct Msgpack-RPC communication with Neovim.
-For this to work, you must add the provided `gemini-integration.lua` file to your Neovim `lua/` configuration directory and require it in your `init.lua`:
+For this to work flawlessly across multiple Neovim instances (even split across Windows and WSL), you must load the provided gemini-integration.lua file in your Neovim init.lua:
-```lua
+`lua
-require('gemini-integration')
+dofile("C:/Users/reazul.ashraf/workspace/rust/mcp-memory/gemini-integration.lua")
-```
+`
-This script allows Neovim to broadcast its active socket to `~/.gemini/active_nvim.txt` when it gains focus, allowing the MCP servers to bridge the connection.
 
-These MCP servers provide the following two-way integration tools:
+### The "Last Focused Wins" Architecture
-*   **`nvim_goto_line`**: Open files and jump cursors directly from the LLM.
+When you use the gemini-integration.lua script, Neovim acts as an active telemetry broadcaster. 
-*   **`nvim_set_diagnostics`**: Push inline code review warnings as virtual text.
+Whenever you alt-tab into a Neovim window (FocusGained) or switch files (BufEnter):
-*   **`nvim_get_active_buffer`**: Read live, unsaved buffer contents.
+1. **Fallback Sync:** Neovim instantly writes its unique Session ID (Named Pipe / Unix Socket) to ~/.gemini/active_nvim.txt.
-*   **`nvim_get_cursor`**: Fetch precise line/column coordinates.
+2. **WebSocket Telemetry:** Neovim pushes a JSON payload containing the active filename, cursor row, and column to the Rust server's /nvim/telemetry webhook.
-*   **`nvim_get_visual_selection`**: Read highlighted code blocks.
+3. **UI Broadcast:** The Rust server updates the global state and broadcasts this over WebSockets (/ws) so that the Brain Monitor Dashboard can animate your active file live in the UI!
+
+### Neovim MCP Tools
+The LLM agent interacts with your active Neovim session using a dedicated set of MCP tools. *(Note: /nvim/telemetry is strictly a one-way webhook for Neovim; the LLM uses the tools below to interact).*
+*   **
+vim_goto_line**: Open files and jump cursors directly from the LLM.
+*   **
+vim_set_diagnostics**: Push inline code review warnings as virtual text.
+*   **
+vim_get_active_buffer**: Read live, unsaved buffer contents.
+*   **
+vim_get_cursor**: Fetch precise line/column coordinates.
+*   **
+vim_get_visual_selection**: Read highlighted code blocks.