docs: Update guidelines and effective discourse for MCP tools

EFFECTIVE_DISCOURSE.md

@@ -43,7 +43,25 @@ Keep your workflow entirely within your editor rather than copy-pasting code blo
 *   **Do say:** "Push this refactor to my active Neovim buffer as ghost text so I can review it in-line."
 *   **Tool Triggered:** `nvim_set_preview` (via `win-nvim` or `linux-nvim`)
 
-## 8. Graph, Memory & Decay Management
+## 8. Structural AST Editing
+When asking the LLM to modify complex files, prevent indentation bugs and regex failures by guiding it to use tree-sitter.
+*   **Don't say:** "Search for `fn process()` and replace it with this string."
+*   **Do say:** "Use the AST node replacer to swap out the `process` function in `server.rs`."
+*   **Tool Triggered:** `replace_ast_node`
+
+## 9. Interactive Terminal Execution
+When asking the LLM to run commands that have prompts, long output, or ANSI colors.
+*   **Don't say:** "Run `cargo run` and tell me what the output is." (Hides output, hangs on prompts).
+*   **Do say:** "Send the `cargo run` command to my Neovim terminal split so I can interact with it."
+*   **Tool Triggered:** `nvim_send_to_terminal`
+
+## 10. Bird's-Eye Repository Exploration
+When the LLM is first analyzing a repository, don't let it run `ls -R` and guess.
+*   **Don't say:** "List the files in the directory and guess where the database code is."
+*   **Do say:** "Read the directory architecture to get a summary of what each file is responsible for."
+*   **Tool Triggered:** `read_directory_architecture`
+
+## 11. Graph, Memory & Decay Management
 Actively instruct the LLM to maintain its own memory constraints and organize data. The daemon automatically consolidates old sticky notes and snippets to prevent unbounded context growth.
 *   **Do say:** "Log this architectural decision in the knowledge graph."
 *   **Do say:** "Add a sticky note with the test database credentials for this session."

README.md

@@ -161,7 +161,7 @@ ead_file_skeleton)**: Uses 	ree-sitter to parse large code files (Rust, Python,
 - **Clipboard Watch Mode (	oggle_clipboard_watch_mode)**: Background daemon thread that auto-ingests your Ctrl+C clipboard activity directly into Knowledge Graph StickyNotes while you debug.
 - **Ghost Text Previews (
 vim_set_preview)**: Pushes proposed LLM code diffs directly into Neovim buffers as ephemeral virtual text.
-- [Prompting Guide & Effective Discourse](./PROMPTING_GUIDE.md): Learn how to phrase prompts to get the most out of the agent and memory server.
+- [Prompting Guide & Effective Discourse](./EFFECTIVE_DISCOURSE.md): Learn how to phrase prompts to get the most out of the agent and memory server.
 
 ## T2R & Token Efficiency Enhancements (V2)
 - **AST Node Replacer (

instructions.md

@@ -115,8 +115,15 @@ To maintain absolute traceability, we link memory items directly to the exact gi
 The project contains two MCP binaries (win-nvim and linux-nvim) that bridge JSON-RPC over stdio directly to the active Neovim instance.
 - **Interactive UI (UDP):** The active editor connects to the backend via UDP (port 3002). The UI script (`gemini-ui.lua`) supports non-destructive **Ghost Text Diff Reviews** and native `vim.ui` prompts without spawning subprocesses. You can trigger these interactively using the backend server.
 - **Tools:** These binaries expose basic tools (`nvim_get_cursor`, `nvim_get_active_buffer`, `nvim_list_buffers`, etc.).
+- **Interactive Execution QoL:** Use `nvim_send_to_terminal` to run background terminal commands (like tests or builds) in a visible Neovim split so the user can interact with prompts and see ANSI colors.
 - **God Mode**: They also expose `nvim_execute_lua`. This is the ultimate fallback tool. If you need to access *any* Neovim API that does not have a dedicated Rust tool (e.g., getting LSP diagnostics, evaluating a visual selection block based on modes, setting registers), you MUST write a short Lua script and pass it to `nvim_execute_lua`. Do not attempt to recompile the Rust server to add new basic tools; use the Lua escape hatch dynamically.
 
-## 16. Tool Schema Discovery (Lazy Loading)
+## 16. Structural Code & Architecture Exploration
-Antigravity automatically caches all MCP tool schemas to your disk to save tokens. Do **NOT** grep or search the Rust source code to find tool schemas or arguments. To understand a tool`s arguments, directly read `~/.gemini/antigravity-cli/mcp/<server_name>/<tool_name>.json`. Do NOT guess arguments. ALWAYS read the schema if you are unfamiliar with a tool to prevent invalid argument errors.
+To reduce token costs and eliminate exact-match string failures:
+- **`read_directory_architecture`**: When exploring a new repository, use this to get a bird's-eye view of a directory structure with summaries of file responsibilities, instead of blindly reading files.
+- **`replace_ast_node`**: Instead of string-matching `replace_file_content` (which fails on whitespace), use this to precisely replace functions or structs based on AST boundaries.
+- **`semantic_code_search`**: Use conceptual vector search instead of raw regex (`grep`) when you need to locate abstract logic (e.g., "Where is authentication handled?").
+
+## 17. Tool Schema Discovery (Lazy Loading)
+Antigravity automatically caches all MCP tool schemas to your disk to save tokens. Do **NOT** grep or search the Rust source code to find tool schemas or arguments. To understand a tool's arguments, directly read `~/.gemini/antigravity-cli/mcp/<server_name>/<tool_name>.json`. Do NOT guess arguments. ALWAYS read the schema if you are unfamiliar with a tool to prevent invalid argument errors.