More emphasis.

packages/core/src/agents/codebase-investigator.test.ts

@@ -11,6 +11,7 @@ import {
   GREP_TOOL_NAME,
   LS_TOOL_NAME,
   READ_FILE_TOOL_NAME,
+  SHELL_TOOL_NAME,
 } from '../tools/tool-names.js';
 import { DEFAULT_GEMINI_MODEL } from '../config/models.js';
 import { makeFakeConfig } from '../test-utils/config.js';
@@ -50,6 +51,7 @@ describe('CodebaseInvestigatorAgent', () => {
       READ_FILE_TOOL_NAME,
       GLOB_TOOL_NAME,
       GREP_TOOL_NAME,
+      SHELL_TOOL_NAME,
     ]);
   });
 

packages/core/src/agents/codebase-investigator.ts

@@ -10,6 +10,7 @@ import {
   GREP_TOOL_NAME,
   LS_TOOL_NAME,
   READ_FILE_TOOL_NAME,
+  SHELL_TOOL_NAME,
 } from '../tools/tool-names.js';
 import {
   DEFAULT_THINKING_MODE,
@@ -114,12 +115,13 @@ export const CodebaseInvestigatorAgent = (
     },
 
     toolConfig: {
-      // Grant access only to read-only tools.
+      // Grant access only to read-only tools and the shell for structural analysis.
       tools: [
         LS_TOOL_NAME,
         READ_FILE_TOOL_NAME,
         GLOB_TOOL_NAME,
         GREP_TOOL_NAME,
+        SHELL_TOOL_NAME,
       ],
     },
 
@@ -131,6 +133,7 @@ export const CodebaseInvestigatorAgent = (
       systemPrompt: `You are **Codebase Investigator**, a hyper-specialized AI agent and an expert in reverse-engineering complex software projects. You are a sub-agent within a larger development system.
 Your **SOLE PURPOSE** is to build a complete mental model of the code relevant to a given investigation. You must identify all relevant files, understand their roles, and foresee the direct architectural consequences of potential changes.
 You are a sub-agent in a larger system. Your only responsibility is to provide deep, actionable context.
+- **DO:** Use \`tilth\` (via the \`run_shell_command\` tool) for initial codebase mapping (\`tilth --map\`) and AST-aware outlines of large files (\`tilth <path>\`).
 - **DO:** Find the key modules, classes, and functions that are part of the problem and its solution.
 - **DO:** Understand *why* the code is written the way it is. Question everything.
 - **DO:** Foresee the ripple effects of a change. If \`function A\` is modified, you must check its callers. If a data structure is altered, you must identify where its type definitions need to be updated.
@@ -141,7 +144,7 @@ You operate in a non-interactive loop and must reason based on the information p
 ---
 ## Core Directives
 <RULES>
-1.  **DEEP ANALYSIS, NOT JUST FILE FINDING:** Your goal is to understand the *why* behind the code. Don't just list files; explain their purpose and the role of their key components. Your final report should empower another agent to make a correct and complete fix.
+1.  **DEEP ANALYSIS, NOT JUST FILE FINDING:** Your goal is to understand the *why* behind the code. Don't just list files; explain their purpose and the role of their key components. Use \`tilth\` for structural awareness and to find definitions quickly. Your final report should empower another agent to make a correct and complete fix.
 2.  **SYSTEMATIC & CURIOUS EXPLORATION:** Start with high-value clues (like tracebacks or ticket numbers) and broaden your search as needed. Think like a senior engineer doing a code review. An initial file contains clues (imports, function calls, puzzling logic). **If you find something you don't understand, you MUST prioritize investigating it until it is clear.** Treat confusion as a signal to dig deeper.
 3.  **HOLISTIC & PRECISE:** Your goal is to find the complete and minimal set of locations that need to be understood or changed. Do not stop until you are confident you have considered the side effects of a potential fix (e.g., type errors, breaking changes to callers, opportunities for code reuse).
 4.  **Web Search:** You are allowed to use the \`web_fetch\` tool to research libraries, language features, or concepts you don't understand (e.g., "what does gettext.translation do with localedir=None?").
@@ -167,7 +170,8 @@ When you are finished, you **MUST** call the \`complete_task\` tool. The \`repor
 {
   "SummaryOfFindings": "The core issue is a race condition in the \`updateUser\` function. The function reads the user's state, performs an asynchronous operation, and then writes the state back. If another request modifies the user state during the async operation, that change will be overwritten. The fix requires implementing a transactional read-modify-write pattern, potentially using a database lock or a versioning system.",
   "ExplorationTrace": [
-    "Used \`grep\` to search for \`updateUser\` to locate the primary function.",
+    "Used \`tilth --map\` to understand the overall project structure.",
+    "Used \`tilth updateUser\` to locate the primary function definition.",
     "Read the file \`src/controllers/userController.js\` to understand the function's logic.",
     "Used ${listCommand} to look for related files, such as services or database models.",
     "Read \`src/services/userService.js\` and \`src/models/User.js\` to understand the data flow and how state is managed."

packages/core/src/core/__snapshots__/prompts.test.ts.snap

@@ -23,9 +23,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -34,12 +36,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -198,9 +200,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -209,12 +213,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -492,9 +496,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -503,12 +509,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -667,9 +673,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -678,12 +686,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -842,9 +850,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -853,12 +863,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -969,9 +979,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -980,12 +992,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -1569,9 +1581,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -1580,12 +1594,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -1740,9 +1754,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -1751,12 +1767,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -1902,9 +1918,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -1913,12 +1931,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -2064,9 +2082,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -2075,12 +2095,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -2222,9 +2242,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -2233,12 +2255,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -2380,9 +2402,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -2391,12 +2415,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -2530,9 +2554,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -2541,12 +2567,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -2687,9 +2713,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -2698,12 +2726,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -2969,9 +2997,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -2980,12 +3010,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -3379,9 +3409,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -3390,12 +3422,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -3537,9 +3569,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -3548,12 +3582,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -3807,9 +3841,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -3818,12 +3854,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -3965,9 +4001,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to grep_search, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`run_shell_command\`) and grep_search to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`run_shell_command\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`read_file\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`run_shell_command\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`read_file\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`run_shell_command\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like read_file and grep_search.
 - read_file fails if old_string is ambiguous, causing extra turns. Take care to read enough with read_file and grep_search to make the edit unambiguous.
@@ -3976,12 +4014,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`run_shell_command\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`run_shell_command\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like grep_search and glob with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
 - **Searching and editing:** utilize search tools like grep_search with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`read_file\` or \`tilth <path> --section 45-89\`. Alternatively, use grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context.
+- **Large files:** Use \`run_shell_command\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 

packages/core/src/prompts/snippets.ts

@@ -23,8 +23,6 @@ import {
   GREP_PARAM_CONTEXT,
   GREP_PARAM_BEFORE,
   GREP_PARAM_AFTER,
-  READ_FILE_PARAM_START_LINE,
-  READ_FILE_PARAM_END_LINE,
   SHELL_PARAM_IS_BACKGROUND,
   EDIT_PARAM_OLD_STRING,
   TRACKER_CREATE_TASK_TOOL_NAME,
@@ -202,9 +200,11 @@ Consider the following when estimating the cost of your approach:
 Use the following guidelines to optimize your search and read patterns.
 <guidelines>
 - Combine turns whenever possible by utilizing parallel searching and reading and by requesting enough context by passing context, before, or after to ${GREP_TOOL_NAME}, to enable you to skip using an extra turn reading the file.
-- Prefer using the \`tilth\` CLI command (via \`${SHELL_TOOL_NAME}\`) and ${GREP_TOOL_NAME} to identify points of interest instead of reading lots of files individually.
-- Utilize \`tilth\` for structural awareness. Use \`${SHELL_TOOL_NAME}\` to run \`tilth <path>\` to get an AST-aware outline of large files, which is more token-efficient than \`${READ_FILE_TOOL_NAME}\`. Run \`tilth --map\` for a high-level codebase overview and \`tilth <query>\` for smart symbol searching that ranks definitions first.
-- **CRITICAL:** Always actively manage your context size when using \`tilth\`. Use the \`--budget <tokens>\` flag (e.g., \`--budget 2000\`) to force \`tilth\` to summarize or truncate its output if it gets too large. Use the \`--section <range>\` flag (e.g., \`--section 10-50\`) to drill down into specific lines.
+- **Structural Awareness:** Prefer the \`tilth\` CLI command (via \`${SHELL_TOOL_NAME}\`) over search tools for initial discovery. \`tilth\` understands code structure (AST) and provides higher signal-to-noise context for symbol discovery and codebase mapping.
+- **Search First:** To explore code, always search first. \`tilth <symbol>\` finds definitions, usages, and file locations in one call. Use directory listing or glob tools ONLY when you have no specific symbol or text to search for.
+- **Avoid Redundancy:** DO NOT use \`${READ_FILE_TOOL_NAME}\` or re-read files if the content you need is already shown in expanded \`tilth\` search results.
+- **AST-Aware Outlines:** Use \`tilth <path>\` via \`${SHELL_TOOL_NAME}\` to get a structural outline of large files. This is significantly more token-efficient than reading the whole file as it shows imports, types, and function signatures while omitting implementation details.
+- **Context Management:** Always manage context size with \`tilth\`. Use \`--budget <tokens>\` (e.g., \`--budget 2000\`) to force truncation/summarization, and \`--section <range>\` (e.g., \`--section 10-50\`) to drill into specific lines.
 - If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
 - It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like ${READ_FILE_TOOL_NAME} and ${GREP_TOOL_NAME}.
 - ${READ_FILE_TOOL_NAME} fails if ${EDIT_PARAM_OLD_STRING} is ambiguous, causing extra turns. Take care to read enough with ${READ_FILE_TOOL_NAME} and ${GREP_TOOL_NAME} to make the edit unambiguous.
@@ -213,12 +213,12 @@ Use the following guidelines to optimize your search and read patterns.
 </guidelines>
 
 <examples>
-- **Initial Discovery:** Use \`${SHELL_TOOL_NAME}\` to run \`tilth --map --budget 2000\` to quickly understand the project structure and token distribution across files safely.
-- **Symbol Exploration:** Use \`${SHELL_TOOL_NAME}\` to run \`tilth <symbol> --budget 1500\` to find both definitions and usages with structural context in a single turn.
+- **Initial Discovery:** Use \`${SHELL_TOOL_NAME}\` to run \`tilth --map --budget 2000\` to get a structural overview of the project and token distribution. This is the fastest way to build a "big picture" mental model.
+- **Symbol Exploration:** Use \`${SHELL_TOOL_NAME}\` to run \`tilth <symbol> --budget 1500\` to find definitions and usages with structural context in a single turn. This is more precise than standard grep.
 - **Searching:** utilize search tools like ${GREP_TOOL_NAME} and ${GLOB_TOOL_NAME} with a conservative result count (\`${GREP_PARAM_TOTAL_MAX_MATCHES}\`) and a narrow scope (\`${GREP_PARAM_INCLUDE_PATTERN}\` and \`${GREP_PARAM_EXCLUDE_PATTERN}\` parameters).
 - **Searching and editing:** utilize search tools like ${GREP_TOOL_NAME} with a conservative result count and a narrow scope. Use \`${GREP_PARAM_CONTEXT}\`, \`${GREP_PARAM_BEFORE}\`, and/or \`${GREP_PARAM_AFTER}\` to request enough context to avoid the need to read the file before editing matches.
 - **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
-- **Large files:** utilize \`${SHELL_TOOL_NAME}\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with \`${READ_FILE_TOOL_NAME}\` or \`tilth <path> --section 45-89\`. Alternatively, use ${GREP_TOOL_NAME} and/or ${READ_FILE_TOOL_NAME} called in parallel with '${READ_FILE_PARAM_START_LINE}' and '${READ_FILE_PARAM_END_LINE}' to reduce the impact on context.
+- **Large files:** Use \`${SHELL_TOOL_NAME}\` to run \`tilth <path> --budget 2000\` to see a file's "skeleton" (imports, types, functions) before deciding which specific sections to read in detail with specialized tools or \`tilth <path> --section 45-89\`.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>