---
name: nvim_editing
description: Route code edits to Neovim buffers instead of disk/console when Neovim is running.
trigger: always_on
---
# Neovim Code Editing (Agnostic & Universal)

These rules apply universally to ALL Neovim environments (Windows, WSL, or any remote server). Do not treat them as OS-specific.

## 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.

## 2. Strict Tool Adherence (No Raw Lua RCE)
You must strictly use the specialized, sandboxed Neovim MCP tools:
- `nvim_buffer`: For reading, writing, saving, and creating scratch buffers.
- `nvim_workspace`: For creating splits and focusing panes.
- `nvim_ui`: For highlighting diffs, adding ghost text, and showing previews.
**DO NOT** use `nvim_exec` (action `lua`) to mutate editor state. It is restricted to **READ-ONLY** queries.

## 3. Headless Quarantine
Headless mode (`nvim --headless`) is strictly banned for interactive edits. 
**NEVER** run `nvim <filename>` via terminal commands to edit or "open" a file for the user (it spawns a zombie ghost process).
Headless instances are allowed ONLY for non-interactive background batch processing (e.g., project-wide formatting or linting).

## 4. UI Presentation & Chat Console Minimization
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_workspace` 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.

## 5. Visual Cues & Auto-Save
When manipulating buffers via MCP:
1. **Focus & Jump:** Always switch the active Neovim window to the edited buffer and jump the cursor to the changed line.
2. **Auto-Save:** Auto-save the buffer by default so linters/compilers see it immediately.
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`).