Encourage tilth usage.

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

@@ -23,7 +23,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -32,10 +34,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -194,7 +198,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -203,10 +209,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -484,7 +492,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -493,10 +503,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -655,7 +667,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -664,10 +678,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -728,7 +744,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use the \`tilth\` CLI command (for structural maps and symbol discovery), \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -826,7 +842,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -835,10 +853,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -869,7 +889,7 @@ Use the following guidelines to optimize your search and read patterns.
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Utilize specialized sub-agents (e.g., \`codebase_investigator\`) as the primary mechanism for initial discovery when the task involves **complex refactoring, codebase exploration or system-wide analysis**. For **simple, targeted searches** (like finding a specific function name, file path, or variable declaration), use \`grep_search\` or \`glob\` directly in parallel. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Utilize specialized sub-agents (e.g., \`codebase_investigator\`) as the primary mechanism for initial discovery when the task involves **complex refactoring, codebase exploration or system-wide analysis**.  For **simple, targeted searches** (like finding a specific function name, file path, or variable declaration), use the \`tilth\` CLI command or \`grep_search\` or \`glob\` directly in parallel. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -949,7 +969,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -958,10 +980,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -992,7 +1016,7 @@ Use the following guidelines to optimize your search and read patterns.
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use the \`tilth\` CLI command (for structural maps and symbol discovery), \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -1545,7 +1569,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -1554,10 +1580,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -1631,7 +1659,7 @@ You have access to the following specialized skills. To activate a skill and rec
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use the \`tilth\` CLI command (for structural maps and symbol discovery), \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -1712,7 +1740,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -1721,10 +1751,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -1785,7 +1817,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use the \`tilth\` CLI command (for structural maps and symbol discovery), \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -1870,7 +1902,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -1879,10 +1913,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -1943,7 +1979,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use the \`tilth\` CLI command (for structural maps and symbol discovery), \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -2028,7 +2064,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -2037,10 +2075,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -2101,7 +2141,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use the \`tilth\` CLI command (for structural maps and symbol discovery), \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -2182,7 +2222,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -2191,10 +2233,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -2255,7 +2299,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use the \`tilth\` CLI command (for structural maps and symbol discovery), \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -2336,7 +2380,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -2345,10 +2391,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -2409,7 +2457,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use the \`tilth\` CLI command (for structural maps and symbol discovery), \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** An approved plan is available for this task. Treat this file as your single source of truth. You MUST read this file before proceeding. If you discover new requirements or need to change the approach, confirm with the user and update this plan file to reflect the updated design decisions or discovered requirements. Once all implementation and verification steps are finished, provide a **final summary** of the work completed against the plan and offer clear **next steps** to the user (e.g., 'Open a pull request').
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -2482,7 +2530,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -2491,10 +2541,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -2635,7 +2687,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -2644,10 +2698,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -2708,7 +2764,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use the \`tilth\` CLI command (for structural maps and symbol discovery), \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -2913,7 +2969,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -2922,10 +2980,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -2986,7 +3046,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use the \`tilth\` CLI command (for structural maps and symbol discovery), \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -3319,7 +3379,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -3328,10 +3390,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -3392,7 +3456,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use the \`tilth\` CLI command (for structural maps and symbol discovery), \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -3473,7 +3537,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -3482,10 +3548,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -3546,7 +3614,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use the \`tilth\` CLI command (for structural maps and symbol discovery), \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -3739,7 +3807,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -3748,10 +3818,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -3812,7 +3884,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use the \`tilth\` CLI command (for structural maps and symbol discovery), \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**
@@ -3893,7 +3965,9 @@ 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 tools like grep_search to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -3902,10 +3976,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.
 - **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 search tools like grep_search and/or read_file called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -3966,7 +4042,7 @@ For example:
 ## Development Lifecycle
 Operate using a **Research -> Strategy -> Execution** lifecycle. For the Execution phase, resolve each sub-task through an iterative **Plan -> Act -> Validate** cycle.
 
-1. **Research:** Systematically map the codebase and validate assumptions. Use \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
+1. **Research:** Systematically map the codebase and validate assumptions. Use the \`tilth\` CLI command (for structural maps and symbol discovery), \`grep_search\` and \`glob\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**
 2. **Strategy:** Formulate a grounded plan based on your research. Share a concise summary of your strategy.
 3. **Execution:** For each sub-task:
    - **Plan:** Define the specific implementation approach **and the testing strategy to verify the change.**

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

@@ -457,7 +457,7 @@ describe('Core System Prompt (prompts.ts)', () => {
           `Utilize specialized sub-agents (e.g., \`codebase_investigator\`) as the primary mechanism for initial discovery`,
         );
         expect(prompt).toContain(
-          'Use `grep_search` and `glob` search tools extensively',
+          'Use the `tilth` CLI command (for structural maps and symbol discovery), `grep_search` and `glob` search tools extensively',
         );
       }
       expect(prompt).toMatchSnapshot();

packages/core/src/prompts/snippets.ts

@@ -202,7 +202,9 @@ 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 tools like ${GREP_TOOL_NAME} to identify points of interest instead of reading lots of files individually.
+- 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.
 - 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.
@@ -211,10 +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.
 - **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 search tools like ${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. Minimize extra turns, unless unavoidable due to the file being too large.
+- **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.
 - **Navigating:** read the minimum required to not require additional turns spent reading the file.
 </examples>
 
@@ -656,17 +660,17 @@ function workflowStepResearch(options: PrimaryWorkflowsOptions): string {
   if (searchTools.length > 0) {
     const toolsStr = searchTools.join(' and ');
     const toolOrTools = searchTools.length > 1 ? 'tools' : 'tool';
-    searchSentence = ` Use ${toolsStr} search ${toolOrTools} extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.`;
+    searchSentence = ` Use the \`tilth\` CLI command (for structural maps and symbol discovery), ${toolsStr} search ${toolOrTools} extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions.`;
   }
 
   if (options.enableCodebaseInvestigator) {
     let subAgentSearch = '';
     if (searchTools.length > 0) {
       const toolsStr = searchTools.join(' or ');
-      subAgentSearch = ` For **simple, targeted searches** (like finding a specific function name, file path, or variable declaration), use ${toolsStr} directly in parallel.`;
+      subAgentSearch = ` For **simple, targeted searches** (like finding a specific function name, file path, or variable declaration), use the \`tilth\` CLI command or ${toolsStr} directly in parallel.`;
     }
 
-    return `1. **Research:** Systematically map the codebase and validate assumptions. Utilize specialized sub-agents (e.g., \`codebase_investigator\`) as the primary mechanism for initial discovery when the task involves **complex refactoring, codebase exploration or system-wide analysis**.${subAgentSearch} Use ${formatToolName(READ_FILE_TOOL_NAME)} to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**${suggestion}`;
+    return `1. **Research:** Systematically map the codebase and validate assumptions. Utilize specialized sub-agents (e.g., \`codebase_investigator\`) as the primary mechanism for initial discovery when the task involves **complex refactoring, codebase exploration or system-wide analysis**. ${subAgentSearch} Use ${formatToolName(READ_FILE_TOOL_NAME)} to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**${suggestion}`;
   }
 
   return `1. **Research:** Systematically map the codebase and validate assumptions.${searchSentence} Use ${formatToolName(READ_FILE_TOOL_NAME)} to validate all assumptions. **Prioritize empirical reproduction of reported issues to confirm the failure state.**${suggestion}`;