feat(embedding,vision): candle embeddings with offline fallback, on-demand clipboard vision capture, and concurrency audit

nvim-core/src/instructions.md

@@ -2,36 +2,59 @@
 
 When connected to this Neovim MCP server (`win-nvim`), you have powerful tools to interact directly with the active Neovim editor.
 
-## The Tool Arsenal
-The following tools are available:
-- **File/Buffer Mgmt:** 
-`nvim_open_file`, `nvim_open_buffer`, `nvim_close_buffer`, `nvim_reload_buffer`, `nvim_save_buffer`, `nvim_list_buffers`
-- **Window Mgmt:**
-`nvim_split_window`, `nvim_close_window`, `nvim_list_windows`, `nvim_get_active_window`, `nvim_set_active_window`
-- **State Reading:** 
-`nvim_get_active_buffer`, `nvim_get_cursor`, `nvim_goto_line`, `nvim_get_visual_selection`, `nvim_get_viewport`, `nvim_get_messages`
-- **Diagnostics & Visuals:** 
-`nvim_set_diagnostics`, `nvim_get_diagnostics`, `nvim_highlight_lines`, `nvim_set_extmark`, `nvim_set_quickfix`
-- **God Mode:** 
-`nvim_execute_lua`
+## The Consolidated Tool Arsenal (v2)
+The server consolidates granular Neovim operations into 7 smart domain tools:
+- **`nvim_buffer`**: Buffer and file management.
+  - `action: "open_file"`: Open file in buffer (args: `file`, `line`, `col`).
+  - `action: "open"`: Open buffer (args: `bufnr`).
+  - `action: "close"`: Close buffer (args: `bufnr`, `force`).
+  - `action: "reload"`: Reload buffer from disk (args: `bufnr`).
+  - `action: "save"`: Save buffer to disk (args: `bufnr`).
+  - `action: "list"`: List all loaded buffers.
+- **`nvim_window`**: Window split and focus management.
+  - `action: "split"`: Split window (args: `direction: "horizontal" | "vertical"`, `file`).
+  - `action: "close"`: Close window (args: `winnr`).
+  - `action: "list"`: List open windows.
+  - `action: "get_active"`: Get active window details.
+  - `action: "set_active"`: Set active window focus (args: `winnr`).
+- **`nvim_view`**: Editor viewport and navigation.
+  - `action: "get_active_buffer"`: Get active buffer details.
+  - `action: "get_cursor"`: Get current cursor line/col.
+  - `action: "goto_line"`: Jump cursor to line (args: `line`, `col`).
+  - `action: "get_viewport"`: Get visible line range in viewport.
+  - `action: "get_messages"`: Get Neovim command-line messages.
+- **`nvim_diagnostics`**: LSP diagnostics querying and publishing.
+  - `action: "get"`: Get diagnostics (args: `bufnr`, `severity`).
+  - `action: "set"`: Set buffer diagnostics (args: `bufnr`, `diagnostics`).
+- **`nvim_visual`**: Visual highlighting, extmarks, and quickfix.
+  - `action: "get_selection"`: Get current visual selection text and range.
+  - `action: "highlight_lines"`: Highlight line ranges (args: `bufnr`, `hl_group`, `start_line`, `end_line`).
+  - `action: "set_extmark"`: Place virtual text or sign extmarks (args: `bufnr`, `ns_id`, `line`, `col`, `opts`).
+  - `action: "set_quickfix"`: Populate quickfix list (args: `items`, `title`).
+- **`nvim_execute_lua`**: God Mode arbitrary Lua evaluation.
+  - Arguments: `code: String`.
+- **`nvim_system`**: System diagnostics and connection heartbeat.
+  - `action: "ping"`: Heartbeat test.
+  - `action: "status"`: Server and socket bridge health status.
 
-## 1. Using Dedicated Tools First
-Always prefer the specific dedicated tools (like `nvim_open_file`, `nvim_highlight_lines`, etc.) over writing raw Lua scripts. These tools are tested and safe.
+## 1. Using Consolidated Domain Tools First
+Always prefer the specific consolidated tools (like `nvim_buffer`, `nvim_window`, `nvim_visual`, etc.) over writing raw Lua scripts. These tools are strongly typed, tested, and safe.
 
 ## 2. Lua God Mode (`nvim_execute_lua`)
-If you need to access *any* Neovim API that does not have a dedicated tool (e.g., complex buffer edits, changing options, LSP interactions), you MUST use `nvim_execute_lua` as your escape hatch.
+If you need to access *any* Neovim API that does not have a dedicated tool (e.g., complex buffer edits, changing options, custom LSP interactions), you MUST use `nvim_execute_lua` as your escape hatch.
 
 ### CRITICAL RULES for `nvim_execute_lua`:
-1. **Never Block:** Never use interactive prompts (`vim.fn.input`, `vim.ui.select`, `vim.fn.confirm`) or confirmation flags in regex substitutions (e.g., `%s/old/new/gc`). This will cause the headless MCP bridge to deadlock forever.
+1. **Never Block:** Never use interactive prompt functions or interactive confirmation flags in substitutions (e.g., `%s/old/new/gc`). This will cause the headless MCP bridge to deadlock forever.
 2. **Visual Feedback:** Always trigger a notification using `require("notify")("Antigravity: [Action]", "info", { title = "Antigravity" })`.
 3. **Auto-Save:** If you modify a file buffer, always save it using `vim.cmd('write')` within the same Lua script so external tools can see the changes, unless you explicitly want to pause for manual human review.
-4. **Buffer Focus:** When making changes to a specific buffer, always ensure the active window is switched to that buffer, and optionally move the cursor so the human can see the change visually.
+4. **Buffer Focus & Centering:** When making changes to a buffer, switch the active window to that buffer, jump to the edited line/column (`vim.api.nvim_win_set_cursor(0, {line, col})`), and center the viewport horizontally and vertically (`vim.cmd('normal! zz'); vim.cmd('normal! ' .. col .. '|zs')`) so the user immediately sees the change in full context.
 
 ## 3. The "Unix is NOT King" Rule
-You should **ALWAYS prioritize Neovim tools over basic unix terminal utilities** (like `cat`, `grep`, `sed`, `awk`, or PowerShell equivalents) for file read/writes and search/replace. If an interactive Neovim session is not currently open, the server will automatically spawn a persistent headless Neovim daemon in the background to execute your commands. 
+You should **ALWAYS prioritize Neovim tools over basic unix terminal utilities** (like `cat`, `grep`, `sed`, `awk`, or PowerShell equivalents) for file read/writes and search/replace. If an interactive Neovim session is not currently open, the server will automatically connect or spawn a persistent headless Neovim daemon in the background to execute your commands. 
 
 **CRITICAL PAIR-PROGRAMMING EXCEPTION:** 
 While the headless background instance is great for autonomous, routine tasks, if you are performing collaborative "pair programming" activities, complex refactors that require visual engagement, or step-by-step human review, **DO NOT** execute them blindly in the background. Instead, explicitly ask the user to open a Neovim UI first so they can visually follow along. Use Neovim as your primary AST-aware interface to the codebase at all times.
 
 ## 4. Tool Schema Discovery
-Do **NOT** grep or search the Rust source code to find tool schemas or arguments. All lazy-loaded MCP tool schemas are automatically cached as JSON files on your disk. To understand a tool`s arguments, directly read `~/.gemini/antigravity-cli/mcp/win-nvim/<tool_name>.json` (or linux-nvim), or simply guess the arguments if it is a basic tool like `nvim_open_file` (e.g., `{"file": "/path/to/file"}`).
+Do **NOT** grep or search the Rust source code to find tool schemas or arguments. All lazy-loaded MCP tool schemas are automatically cached as JSON files on your disk. To understand a tool's arguments, directly read `~/.gemini/antigravity-cli/mcp/win-nvim/<tool_name>.json` (or linux-nvim).
+