docs: strictly enforce agnostic Neovim rules and ban invisible shell edits

agent-rules/nvim_editing.md

@@ -3,32 +3,33 @@ name: nvim_editing
 description: Route code edits to Neovim buffers instead of disk/console when Neovim is running.
 trigger: always_on
 ---
-# Neovim Code Editing
+# Neovim Code Editing (Agnostic & Universal)
 
-## Never Spawn Headless Instances (CRITICAL)
+These rules apply universally to ALL Neovim environments (Windows, WSL, or any remote server). Do not treat them as OS-specific.
-**NEVER** run `nvim <filename>` via bash/terminal commands (`run_command`) to "open" or "show" a file to the user. Because agent terminal commands run in the background, this spawns an invisible ghost process. 
 
-If the user asks to "open", "show", or "see" a file in Neovim, you MUST use the `win-nvim` (Neovim) MCP Server to communicate with their *active* UI (e.g., using `nvim_execute_lua` with `vim.cmd('edit <file>')`).
+## 1. No Invisible Shell Edits (CRITICAL)
+**NEVER** use `sed`, `awk`, `python -c`, or `echo` to modify file contents from the terminal. 
+File edits must use EXACTLY one of two paths:
+- **Active UI (Neovim MCP responsive):** Route edits through specialized MCP tools to provide live visual feedback.
+- **No UI (Neovim MCP unresponsive):** Fall back to the built-in `replace_file_content` tool to generate clean chat diffs.
 
-When making code edits or displaying search results/outputs:
+## 2. Strict Tool Adherence (No Raw Lua RCE)
-1. Verify if the `win-nvim` (Neovim) MCP server is responsive.
+You must strictly use the specialized, sandboxed Neovim MCP tools:
-2. If Neovim is running, apply code changes directly into the relevant Neovim buffers using nvim_execute_lua (e.g., using vim.api.nvim_buf_set_lines or vim.cmd).
+- `nvim_buffer`: For reading, writing, saving, and creating scratch buffers.
-3. DO NOT output large diffs or file contents to the chat console. Prefer live buffer manipulation over replace_file_content if the file is open in Neovim.
+- `nvim_window`: For creating splits and focusing panes.
-4. **Fallback Constraint (CRITICAL):** If Neovim is NOT running, you MUST use the `replace_file_content` tool to edit files. This ensures the user is presented with a visual diff block in the chat. **NEVER** use `sed`, `awk`, or `echo` to blindly modify file contents from the terminal.
+- `nvim_visual`: For highlighting diffs, adding ghost text, and showing previews.
+**DO NOT** use `nvim_execute_lua` to mutate editor state. It is restricted to **READ-ONLY** queries.
 
-## Visual Cues & Auto-Save Policy (MANDATORY)
+## 3. Headless Quarantine
-When manipulating buffers via Lua, you MUST provide visual feedback:
+Headless mode (`nvim --headless`) is strictly banned for interactive edits. 
-1. **Notifications:** Always trigger a notification explaining what you did using `require("notify")("Antigravity edited [File]: [Summary]", "info", { title = "Antigravity" })` (since `rcarriga/nvim-notify` and `noice.nvim` are installed).
+**NEVER** run `nvim <filename>` via terminal commands to edit or "open" a file for the user (it spawns a zombie ghost process).
-2. **Buffer Focus:** Always switch the active Neovim window to the buffer you just edited (e.g., `vim.cmd('b ' .. bufnr)`).
+Headless instances are allowed ONLY for non-interactive background batch processing (e.g., project-wide formatting or linting).
-3. **Cursor Jump:** Move the cursor to the line you edited (`vim.api.nvim_win_set_cursor(0, {line, 0})`).
-4. **Auto-Save by Default:** You MUST save the buffer (`vim.cmd('write')`) after making edits so that external tools (tests, compilers, linters, git) can see the changes immediately and unattended tasks are not stalled.
-5. **Interactive Review Mode (Exception):** The ONLY time you should disable auto-save (leaving the buffer modified and unsaved) is when you are actively halting execution to seek manual user confirmation for a highly sensitive change. This allows the user to visually review the `gitsigns` diff in the gutter before manually saving (`:w`).
 
-## Interactive Review & Automatic Wakeup (MANDATORY)
+## 4. UI Presentation & Chat Console Minimization
-When you modify a buffer and disable auto-save to allow the user to visually review the changes, you MUST NOT just wait idly for them to chat back.
+Never output large plans, context blocks, or architectural discussions to the chat console if Neovim is running. You MUST use the `nvim_buffer` and `nvim_window` tools to open a vertical split (e.g., `Antigravity_Plan.md` scratch buffer) and present the markdown natively. Reserve the chat console strictly for brief confirmations.
-You MUST spawn a background task to listen for their :w save event:
+
-1. Use the ␍un_command tool to execute: 
+## 5. Visual Cues & Auto-Save
-   curl -s "http://127.0.0.1:3000/events/wait?topic=nvim:save:$((Get-Item $File).FullName.Replace('\', '/'))&session_id=$SessionId"
+When manipulating buffers via MCP:
-2. Set WaitMsBeforeAsync to a low value (e.g., 500ms) so it goes to the background immediately.
+1. **Focus & Jump:** Always switch the active Neovim window to the edited buffer and jump the cursor to the changed line.
-3. Stop calling tools and end your turn. 
+2. **Auto-Save:** Auto-save the buffer by default so linters/compilers see it immediately.
-When the user saves the file, the curl command will complete and the system will automatically wake you up to proceed.
+3. **Interactive Review:** If pausing for human review (leaving unsaved), you MUST spawn a background `curl` task listening to `http://127.0.0.1:3000/events/wait?topic=nvim:save...` to wake you up when the user saves (`:w`).