docs: reorganize file_cache.py with region tags and update tooling guidelines

GEMINI.md

@@ -40,6 +40,7 @@
     *   `manual_slop.toml`: Per-project settings (files to track, discussion history, specific system prompts).
 *   **Tool Execution:** The AI acts primarily by generating PowerShell scripts. These scripts MUST be confirmed by the user via a GUI modal before execution. The AI also has access to read-only MCP-style file exploration tools and web search capabilities.
 *   **Context Refresh:** After every tool call that modifies the file system, the application automatically refreshes the file contents in the context using the files' `mtime` to optimize reads.
+*   **Sequential Tooling:** Tools that rely on line numbers (e.g., `py_region_wrap`, `get_file_slice`, `set_file_slice`) MUST be executed sequentially across multiple turns. Never batch multiple line-dependent operations in a single turn, as preceding edits will cause line drift and corrupt subsequent operations.
 *   **UI State Persistence:** Window layouts and docking arrangements are automatically saved to and loaded from `dpg_layout.ini`.
 *   **Code Style:**
     *   Use type hints where appropriate.

src/file_cache.py

@@ -50,7 +50,7 @@ class ASTParser:
      Parser for extracting AST-based views of source code.
      Currently supports Python.
  """
-
+ #region: Core Operations
  def __init__(self, language: str) -> None:
   """
   [C: src/mcp_client.py:_DDGParser.__init__, src/mcp_client.py:_TextExtractor.__init__]
@@ -180,7 +180,8 @@ class ASTParser:
     if child.type in ("type_identifier", "identifier", "namespace_identifier", "qualified_identifier"):
      return code_bytes[child.start_byte:child.end_byte].decode("utf8", errors="replace")
   return ""
-
+ #endregion: Core Operations
+ #region: Skeleton & Curated Views
  def get_skeleton(self, code: str, path: Optional[str] = None) -> str:
   """
   
@@ -234,7 +235,6 @@ class ASTParser:
   for start, end, replacement in edits:
    code_bytearray[start:end] = bytes(replacement, "utf8")
   return code_bytearray.decode("utf8")
-
  def get_curated_view(self, code: str, path: Optional[str] = None) -> str:
   """
   
@@ -311,7 +311,9 @@ class ASTParser:
   for start, end, replacement in edits:
    code_bytearray[start:end] = bytes(replacement, "utf8")
   return code_bytearray.decode("utf8")
+ #endregion: Skeleton & Curated Views
 
+ #region: Targeted Views
  def get_targeted_view(self, code: str, function_names: List[str], path: Optional[str] = None) -> str:
   """
   
@@ -475,10 +477,11 @@ class ASTParser:
   result = code_bytearray.decode("utf8")
   result = re.sub(r'\n\s*\n\s*\n+', '\n\n', result)
   return result.strip() + "\n"
+ #endregion: Targeted Views
 
+ #region: Symbol Extraction
  def get_definition(self, code: str, name: str, path: Optional[str] = None) -> str:
   """
-  
     Returns the full source code for a specific definition by name.
     Supports 'ClassName::method' or 'method' for C++.
     [C: src/mcp_client.py:trace, src/mcp_client.py:ts_c_get_definition, src/mcp_client.py:ts_cpp_get_definition, tests/test_ast_parser.py:test_ast_parser_get_definition_c, tests/test_ast_parser.py:test_ast_parser_get_definition_cpp, tests/test_ast_parser.py:test_ast_parser_get_definition_cpp_template]
@@ -678,7 +681,9 @@ class ASTParser:
    return code_bytes[found_node.start_byte:found_node.end_byte].decode("utf8", errors="replace").strip()
 
   return f"ERROR: signature for '{name}' not found"
+ #endregion: Symbol Extraction
 
+ #region: Analysis & Updates
  def get_code_outline(self, code: str, path: Optional[str] = None) -> str:
   """
   
@@ -816,10 +821,13 @@ class ASTParser:
    code_bytearray[found_node.start_byte:found_node.end_byte] = bytes(new_content, "utf8")
    return code_bytearray.decode("utf8")
   return f"ERROR: definition '{name}' not found"
+ #endregion: Analysis & Updates
 
+#region: Module Level Utilities
 def reset_client() -> None:
  pass
 
 def get_file_id(path: Path) -> Optional[str]:
  return None
+#endregion: Module Level Utilities