zblade.dev/src/pages/tools.astro

---
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout title="Tool Calls Reference - Zaguán Blade" description="Complete reference for all tool calls available in Zaguán Blade for Local AI system prompts.">
  <main>
    <!-- Hero Section -->
    <section class="tools-hero">
      <div class="container">
        <nav class="breadcrumb">
          <a href="/docs">Docs</a>
          <span class="breadcrumb-sep">/</span>
          <span class="breadcrumb-current">Tool Calls</span>
        </nav>
        <div class="hero-content">
          <div class="hero-label">// TOOL_CALLS.md</div>
          <h1 class="hero-title">
            <span class="title-line-1">TOOL CALLS</span>
            <span class="title-accent">REFERENCE_</span>
          </h1>
          <p class="hero-description">
            Complete reference for all tool calls available in Zaguán Blade.
            Add these to your Local AI system prompts to enable file operations, search, editor control, and command execution.
          </p>
          <div class="hero-note">
            <span class="hero-note-label">NOTE</span>
            <span class="hero-note-text">This does not cover Blade-specific or ZLP (Zaguán Language Protocol) tools. These are standard file/editor tools for general AI coding assistance.</span>
          </div>
        </div>
      </div>
    </section>

    <!-- Quick Nav -->
    <section class="quick-nav">
      <div class="container">
        <div class="nav-strip">
          <a href="#file-operations" class="nav-chip">File Operations</a>
          <a href="#directory-search" class="nav-chip">Directory & Search</a>
          <a href="#editor-interaction" class="nav-chip">Editor Interaction</a>
          <a href="#command-execution" class="nav-chip">Command Execution</a>
          <a href="#tool-result-handling" class="nav-chip">Result Handling</a>
          <a href="#path-resolution" class="nav-chip">Path Resolution</a>
          <a href="#system-prompt-integration" class="nav-chip">System Prompt</a>
        </div>
      </div>
    </section>

    <!-- File Operations Section -->
    <section id="file-operations" class="docs-section">
      <div class="container">
        <div class="section-label">[001] FILE_OPERATIONS</div>
        <h2 class="section-title">File Operations</h2>
        
        <div class="tools-list">
          <!-- read_file -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">read_file</span>
                <span class="tool-tag">READ</span>
              </div>
              <p class="tool-desc">Read the complete contents of a file.</p>
              <div class="tool-aliases">Aliases: <code>file_path</code>, <code>filepath</code>, <code>filename</code></div>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>path</code></td><td><span class="type-badge req">required</span> string</td><td>File path (relative to workspace or absolute)</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{ "path": "src/main.rs" }</code></pre>
              </div>
            </div>
          </div>

          <!-- read_file_range -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">read_file_range</span>
                <span class="tool-tag">READ</span>
              </div>
              <p class="tool-desc">Read a specific line range from a file with optional context.</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>path</code></td><td><span class="type-badge req">required</span> string</td><td>File path</td></tr>
                    <tr><td><code>start_line</code></td><td><span class="type-badge opt">optional</span> integer</td><td>Start line (1-indexed, default: 1)</td></tr>
                    <tr><td><code>end_line</code></td><td><span class="type-badge opt">optional</span> integer</td><td>End line (1-indexed, default: end of file)</td></tr>
                    <tr><td><code>context_lines</code></td><td><span class="type-badge opt">optional</span> integer</td><td>Extra context lines before/after range (default: 0)</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{
  "path": "src/lib.rs",
  "start_line": 50,
  "end_line": 100,
  "context_lines": 3
}</code></pre>
              </div>
            </div>
          </div>

          <!-- write_file -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">write_file</span>
                <span class="tool-sep">/</span>
                <span class="tool-name">create_file</span>
                <span class="tool-tag">WRITE</span>
              </div>
              <p class="tool-desc">Write content to a file. Creates parent directories if needed.</p>
              <div class="tool-aliases">Content aliases: <code>contents</code>, <code>text</code>, <code>data</code></div>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>path</code></td><td><span class="type-badge req">required</span> string</td><td>File path</td></tr>
                    <tr><td><code>content</code></td><td><span class="type-badge req">required</span> string</td><td>Content to write</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{
  "path": "src/new_module.rs",
  "content": "pub fn hello() {\n    println!(\"Hello!\");\n}\n"
}</code></pre>
              </div>
            </div>
          </div>

          <!-- edit_file -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">edit_file</span>
                <span class="tool-tag">EDIT</span>
                <span class="tool-tag tool-tag-legacy">LEGACY</span>
              </div>
              <p class="tool-desc">Apply a search/replace edit to a file (legacy tool).</p>
              <div class="tool-aliases">Aliases: <code>old</code>/<code>from</code> for old_content, <code>new</code>/<code>to</code> for new_content</div>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>path</code></td><td><span class="type-badge req">required</span> string</td><td>File path</td></tr>
                    <tr><td><code>old_content</code></td><td><span class="type-badge req">required</span> string</td><td>Text to find</td></tr>
                    <tr><td><code>new_content</code></td><td><span class="type-badge req">required</span> string</td><td>Replacement text</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{
  "path": "src/main.rs",
  "old_content": "fn old_function()",
  "new_content": "fn new_function()"
}</code></pre>
              </div>
            </div>
          </div>

          <!-- apply_patch -->
          <div class="tool-card tool-featured">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">apply_edit</span>
                <span class="tool-sep">/</span>
                <span class="tool-name">apply_patch</span>
                <span class="tool-tag">EDIT</span>
                <span class="tool-tag tool-tag-recommended">RECOMMENDED</span>
              </div>
              <p class="tool-desc">Apply search/replace edits with robust fuzzy matching. Supports both single patches and atomic multi-patch operations.</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Single Patch Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>path</code></td><td><span class="type-badge req">required</span> string</td><td>File path</td></tr>
                    <tr><td><code>old_text</code></td><td><span class="type-badge req">required</span> string</td><td>Text to find and replace</td></tr>
                    <tr><td><code>new_text</code></td><td><span class="type-badge req">required</span> string</td><td>Replacement text</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-params">
                <h4>Multi-Patch Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>path</code></td><td><span class="type-badge req">required</span> string</td><td>File path</td></tr>
                    <tr><td><code>patches</code></td><td><span class="type-badge req">required</span> array</td><td>Array of patch objects</td></tr>
                  </tbody>
                </table>
                <div class="patch-fields">
                  Each patch: <code>old_text</code>, <code>new_text</code>, optional <code>start_line</code>/<code>end_line</code> hints
                </div>
              </div>
              <div class="tool-examples-row">
                <div class="tool-example">
                  <h4>Single Patch</h4>
                  <pre is:raw><code>{
  "path": "src/lib.rs",
  "old_text": "let x = 5;",
  "new_text": "let x = 10;"
}</code></pre>
                </div>
                <div class="tool-example">
                  <h4>Multi-Patch</h4>
                  <pre is:raw><code>{
  "path": "src/lib.rs",
  "patches": [
    {"old_text": "fn foo()", "new_text": "fn bar()"},
    {"old_text": "let a = 1;", "new_text": "let a = 2;"}
  ]
}</code></pre>
                </div>
              </div>
              <div class="tool-note">
                <span class="note-icon">ℹ️</span>
                <p class="note-text">Multi-patch operations are atomic - all patches are validated before any are applied. If any patch fails, no changes are made.</p>
              </div>
            </div>
          </div>

          <!-- delete_file -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">delete_file</span>
                <span class="tool-tag tag-danger">DELETE</span>
              </div>
              <p class="tool-desc">Delete a file or directory.</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>path</code></td><td><span class="type-badge req">required</span> string</td><td>Path to delete</td></tr>
                    <tr><td><code>recursive</code></td><td><span class="type-badge opt">optional</span> boolean</td><td>Required for directories (default: false)</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{ "path": "temp/old_file.txt" }</code></pre>
              </div>
            </div>
          </div>

          <!-- move_file -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">move_file</span>
                <span class="tool-tag">MOVE</span>
              </div>
              <p class="tool-desc">Move or rename a file.</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>source</code></td><td><span class="type-badge req">required</span> string</td><td>Source path</td></tr>
                    <tr><td><code>destination</code></td><td><span class="type-badge req">required</span> string</td><td>Destination path</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{
  "source": "src/old_name.rs",
  "destination": "src/new_name.rs"
}</code></pre>
              </div>
            </div>
          </div>

          <!-- copy_file -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">copy_file</span>
                <span class="tool-tag">COPY</span>
              </div>
              <p class="tool-desc">Copy a file or directory (recursive for directories).</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>source</code></td><td><span class="type-badge req">required</span> string</td><td>Source path</td></tr>
                    <tr><td><code>destination</code></td><td><span class="type-badge req">required</span> string</td><td>Destination path</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{
  "source": "templates/base.html",
  "destination": "src/templates/base.html"
}</code></pre>
              </div>
            </div>
          </div>

          <!-- get_file_info -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">get_file_info</span>
                <span class="tool-tag">INFO</span>
              </div>
              <p class="tool-desc">Get metadata about a file or directory.</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>path</code></td><td><span class="type-badge req">required</span> string</td><td>Path to inspect</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-returns">
                <h4>Returns</h4>
                <div class="returns-fields">
                  <code>path</code> <code>size</code> <code>is_directory</code> <code>is_file</code> <code>modified</code> <code>readonly</code>
                </div>
              </div>
            </div>
          </div>

          <!-- create_directory -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">create_directory</span>
                <span class="tool-tag">CREATE</span>
              </div>
              <p class="tool-desc">Create a directory (and parent directories if needed).</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>path</code></td><td><span class="type-badge req">required</span> string</td><td>Directory path to create</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{ "path": "src/modules/new_feature" }</code></pre>
              </div>
            </div>
          </div>
        </div>
      </div>
    </section>

    <!-- Directory & Search Tools Section -->
    <section id="directory-search" class="docs-section section-alt">
      <div class="container">
        <div class="section-label">[002] DIRECTORY_&_SEARCH</div>
        <h2 class="section-title">Directory & Search Tools</h2>
        
        <div class="tools-list">
          <!-- list_dir -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">list_directory</span>
                <span class="tool-sep">/</span>
                <span class="tool-name">list_dir</span>
                <span class="tool-tag">DIRECTORY</span>
              </div>
              <p class="tool-desc">List directory contents with tree view.</p>
              <div class="tool-aliases">Aliases: <code>dir</code>, <code>directory</code></div>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>path</code></td><td><span class="type-badge opt">optional</span> string</td><td>Directory path (default: ".")</td></tr>
                    <tr><td><code>max_depth</code></td><td><span class="type-badge opt">optional</span> integer</td><td>Max traversal depth (default: 1)</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{
  "path": "src",
  "max_depth": 2
}</code></pre>
              </div>
            </div>
          </div>

          <!-- get_workspace_structure -->
          <div class="tool-card tool-featured">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">get_workspace_structure</span>
                <span class="tool-tag">PROJECT</span>
                <span class="tool-tag tool-tag-recommended">RECOMMENDED</span>
              </div>
              <p class="tool-desc">Get a tree view of the workspace structure.</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>path</code></td><td><span class="type-badge opt">optional</span> string</td><td>Starting path (default: ".")</td></tr>
                    <tr><td><code>depth</code></td><td><span class="type-badge opt">optional</span> integer</td><td>Max depth (default: 2)</td></tr>
                    <tr><td><code>limit</code></td><td><span class="type-badge opt">optional</span> integer</td><td>Max entries (default: 50, max: 200)</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{
  "path": ".",
  "depth": 3,
  "limit": 100
}</code></pre>
              </div>
              <div class="tool-note">
                <span class="note-icon">ℹ️</span>
                <p class="note-text">Automatically ignores common directories like <code>node_modules</code>, <code>target</code>, <code>.git</code>, <code>__pycache__</code>, etc.</p>
              </div>
            </div>
          </div>

          <!-- find_files -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">find_files</span>
                <span class="tool-tag">SEARCH</span>
              </div>
              <p class="tool-desc">Find files by name pattern (substring match).</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>pattern</code></td><td><span class="type-badge req">required</span> string</td><td>Substring to match in filenames</td></tr>
                    <tr><td><code>path</code></td><td><span class="type-badge opt">optional</span> string</td><td>Starting path (default: workspace root)</td></tr>
                    <tr><td><code>max_depth</code></td><td><span class="type-badge opt">optional</span> integer</td><td>Max search depth</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{
  "pattern": "test",
  "path": "src",
  "max_depth": 5
}</code></pre>
              </div>
            </div>
          </div>

          <!-- find_files_glob -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">find_files_glob</span>
                <span class="tool-sep">/</span>
                <span class="tool-name">glob</span>
                <span class="tool-tag">SEARCH</span>
              </div>
              <p class="tool-desc">Find files using glob patterns.</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>pattern</code></td><td><span class="type-badge req">required</span> string</td><td>Glob pattern (e.g., <code>**/*.rs</code>)</td></tr>
                    <tr><td><code>path</code></td><td><span class="type-badge opt">optional</span> string</td><td>Base path for search</td></tr>
                    <tr><td><code>case_sensitive</code></td><td><span class="type-badge opt">optional</span> boolean</td><td>Case-sensitive matching (default: false)</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{
  "pattern": "**/*.tsx",
  "path": "src"
}</code></pre>
              </div>
            </div>
          </div>

          <!-- grep_search -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">grep_search</span>
                <span class="tool-sep">/</span>
                <span class="tool-name">rg</span>
                <span class="tool-tag">CONTENT</span>
              </div>
              <p class="tool-desc">Search file contents using regex patterns.</p>
              <div class="tool-aliases">Pattern aliases: <code>query</code>, <code>regex</code></div>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>pattern</code></td><td><span class="type-badge req">required</span> string</td><td>Regex pattern to search</td></tr>
                    <tr><td><code>path</code></td><td><span class="type-badge opt">optional</span> string</td><td>Directory to search (default: ".")</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{
  "pattern": "fn\\s+main",
  "path": "src"
}</code></pre>
              </div>
              <div class="tool-returns">
                <h4>Returns</h4>
                <p>Matches in format <code>filepath:line_number:line_content</code></p>
              </div>
            </div>
          </div>

          <!-- codebase_search -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">codebase_search</span>
                <span class="tool-tag">CONTENT</span>
              </div>
              <p class="tool-desc">Search codebase with context lines around matches.</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>query</code></td><td><span class="type-badge req">required</span> string</td><td>Regex pattern to search</td></tr>
                    <tr><td><code>file_pattern</code></td><td><span class="type-badge opt">optional</span> string</td><td>Filter files (e.g., <code>*.rs,*.toml</code>)</td></tr>
                    <tr><td><code>max_results</code></td><td><span class="type-badge opt">optional</span> integer</td><td>Maximum results (default: 50)</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{
  "query": "struct.*Config",
  "file_pattern": "*.rs",
  "max_results": 20
}</code></pre>
              </div>
              <div class="tool-returns">
                <h4>Returns</h4>
                <p>Matches with 2 lines of context before and after.</p>
              </div>
            </div>
          </div>
        </div>
      </div>
    </section>

    <!-- Editor Interaction Tools Section -->
    <section id="editor-interaction" class="docs-section">
      <div class="container">
        <div class="section-label">[003] EDITOR_INTERACTION</div>
        <h2 class="section-title">Editor Interaction Tools</h2>
        
        <div class="tools-list">
          <!-- get_editor_state -->
          <div class="tool-card tool-featured">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">get_editor_state</span>
                <span class="tool-tag">INFO</span>
                <span class="tool-tag tool-tag-recommended">RECOMMENDED</span>
              </div>
              <p class="tool-desc">Get current editor context including active file, cursor position, and open files.</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <p class="no-params">None</p>
              </div>
              <div class="tool-returns">
                <h4>Returns</h4>
                <div class="returns-fields">
                  <code>active_file</code> <code>open_files</code> <code>active_tab_index</code> <code>cursor_line</code> <code>cursor_column</code> <code>selection_start_line</code> <code>selection_end_line</code>
                </div>
              </div>
            </div>
          </div>

          <!-- open_file -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">open_file</span>
                <span class="tool-tag">CONTROL</span>
              </div>
              <p class="tool-desc">Open a file in the editor.</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>path</code></td><td><span class="type-badge req">required</span> string</td><td>File path to open</td></tr>
                    <tr><td><code>line</code></td><td><span class="type-badge opt">optional</span> integer</td><td>Line number to jump to</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{
  "path": "src/main.rs",
  "line": 42
}</code></pre>
              </div>
            </div>
          </div>

          <!-- goto_line -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">goto_line</span>
                <span class="tool-tag">CONTROL</span>
              </div>
              <p class="tool-desc">Navigate to a specific line in the active file.</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>line</code></td><td><span class="type-badge req">required</span> integer</td><td>Line number (1-indexed)</td></tr>
                    <tr><td><code>column</code></td><td><span class="type-badge opt">optional</span> integer</td><td>Column number</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{
  "line": 100,
  "column": 15
}</code></pre>
              </div>
            </div>
          </div>

          <!-- get_selection -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">get_selection</span>
                <span class="tool-tag">SELECTION</span>
              </div>
              <p class="tool-desc">Get the currently selected text in the editor.</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <p class="no-params">None</p>
              </div>
              <div class="tool-returns">
                <h4>Returns</h4>
                <p>The selected text content.</p>
              </div>
            </div>
          </div>

          <!-- replace_selection -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">replace_selection</span>
                <span class="tool-tag">EDIT</span>
              </div>
              <p class="tool-desc">Replace the current selection with new content.</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>content</code></td><td><span class="type-badge req">required</span> string</td><td>Replacement content</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{ "content": "new replacement text" }</code></pre>
              </div>
            </div>
          </div>

          <!-- insert_at_cursor -->
          <div class="tool-card">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">insert_at_cursor</span>
                <span class="tool-tag">EDIT</span>
              </div>
              <p class="tool-desc">Insert content at the current cursor position.</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>content</code></td><td><span class="type-badge req">required</span> string</td><td>Content to insert</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{ "content": "// TODO: implement this\n" }</code></pre>
              </div>
            </div>
          </div>
        </div>
      </div>
    </section>

    <!-- Command Execution Section -->
    <section id="command-execution" class="docs-section section-alt">
      <div class="container">
        <div class="section-label">[004] COMMAND_EXECUTION</div>
        <h2 class="section-title">Command Execution</h2>
        
        <div class="tools-list">
          <!-- run_command -->
          <div class="tool-card tool-featured">
            <div class="tool-header">
              <div class="tool-title-row">
                <span class="tool-name">run_command</span>
                <span class="tool-tag">TERMINAL</span>
              </div>
              <p class="tool-desc">Execute a shell command (requires user approval).</p>
            </div>
            <div class="tool-body">
              <div class="tool-params">
                <h4>Parameters</h4>
                <table class="params-table">
                  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
                  <tbody>
                    <tr><td><code>command</code></td><td><span class="type-badge req">required</span> string</td><td>Shell command to execute</td></tr>
                    <tr><td><code>cwd</code></td><td><span class="type-badge req">required</span> string</td><td>Working directory</td></tr>
                  </tbody>
                </table>
              </div>
              <div class="tool-example">
                <h4>Example</h4>
                <pre is:raw><code>{
  "command": "cargo build --release",
  "cwd": "."
}</code></pre>
              </div>
              <div class="tool-note tool-note-warning">
                <span class="note-icon">⚠️</span>
                <p class="note-text">This tool requires user confirmation before execution for safety.</p>
              </div>
            </div>
          </div>
        </div>
      </div>
    </section>

    <!-- Tool Result Handling Section -->
    <section id="tool-result-handling" class="docs-section">
      <div class="container">
        <div class="section-label">[005] TOOL_RESULTS</div>
        <h2 class="section-title">Tool Result Handling</h2>
        
        <div class="info-card">
          <p class="info-text">The 50KB / 2000 line limits apply <strong>only to tool results</strong> - what zblade sends back to the model after executing a tool (e.g., the output of <code>read_file</code>). These limits only apply in <strong>local mode</strong>, when the Zagu&aacute;n Coder Daemon isn't handling storage.</p>
          <div class="limits-row">
            <div class="limit-box">
              <span class="limit-value">50KB</span>
              <span class="limit-label">Result max size</span>
            </div>
            <div class="limit-box">
              <span class="limit-value">2000</span>
              <span class="limit-label">Result max lines</span>
            </div>
          </div>
          <p class="info-text-secondary">When truncated, the first 100 lines and last 50 lines are shown with a truncation message.</p>
        </div>

        <div class="info-card" style="margin-top: var(--space-lg);">
          <p class="info-text"><strong>There are no size limits on incoming tool calls from the model.</strong> zblade will accept a <code>write_file</code> with any size content. The <code>write_file</code> handler itself has no caps - it writes whatever content string it receives directly to disk.</p>
        </div>

        <div class="tool-note" style="margin-top: var(--space-lg);">
          <span class="note-icon">ℹ️</span>
          <p class="note-text">zblade includes <strong>dropped tool call detection</strong>. If a tool call from the model never arrives (e.g., streaming progress events complete but the final tool call with arguments is dropped server-side), zblade will catch this and surface a clear error.</p>
        </div>
      </div>
    </section>

    <!-- Path Resolution Section -->
    <section id="path-resolution" class="docs-section section-alt">
      <div class="container">
        <div class="section-label">[006] PATH_RESOLUTION</div>
        <h2 class="section-title">Path Resolution</h2>
        
        <div class="info-card">
          <p class="info-text">All paths can be:</p>
          <div class="path-options">
            <div class="path-option">
              <span class="path-badge">Relative</span>
              <span class="path-text">Resolved from workspace root (e.g., <code>src/main.rs</code>)</span>
            </div>
            <div class="path-option">
              <span class="path-badge">Absolute</span>
              <span class="path-text">Used as-is (must be within workspace)</span>
            </div>
          </div>
          <div class="tool-note tool-note-warning">
            <span class="note-icon">⚠️</span>
            <p class="note-text">Paths outside the workspace are rejected for security.</p>
          </div>
        </div>
      </div>
    </section>

    <!-- System Prompt Integration Section -->
    <section id="system-prompt-integration" class="docs-section">
      <div class="container">
        <div class="section-label">[007] SYSTEM_PROMPT</div>
        <h2 class="section-title">Adding Tools to Your AI System Prompt</h2>
        
        <div class="prompt-intro">
          <p class="info-text">
            To use these tools with a local AI, include the tool definitions in your system prompt. See the <a href="/docs#local-ai-prompts">Local AI System Prompts</a> section for setup instructions.
          </p>
          
          <div class="code-block">
            <div class="code-header">
              <span class="code-filename">Example System Prompt Snippet</span>
              <span class="code-lang">markdown</span>
            </div>
            <pre is:raw><code># Available Tools

**get_workspace_structure** - Get project directory tree
**list_dir** - List files/directories in a path
**read_file** - Read file contents
**write_file** - Create or overwrite a file
**apply_patch** - Replace specific content in a file (for edits)
**grep_search** - Search for patterns across files
**run_command** - Execute shell commands (use cwd parameter)
**get_editor_state** - Get currently open file and cursor position</code></pre>
          </div>
          
          <p class="info-text-secondary">
            The exact format depends on your AI provider's tool calling conventions.
          </p>
        </div>
      </div>
    </section>
  </main>
</BaseLayout>

<style>
  /* ===== Hero ===== */
  .tools-hero {
    min-height: 50vh;
    display: flex;
    align-items: center;
    padding-top: calc(var(--space-3xl) + 60px);
    padding-bottom: var(--space-2xl);
    background: linear-gradient(180deg, var(--color-bg) 0%, var(--color-bg-secondary) 100%);
    border-bottom: 1px solid var(--color-border);
  }

  .tools-hero .hero-content {
    max-width: 800px;
  }

  .tools-hero .hero-title {
    margin-bottom: var(--space-lg);
  }

  .title-line-1 {
    display: block;
    font-size: clamp(2.5rem, 8vw, 5rem);
    font-weight: 900;
    line-height: 0.95;
    letter-spacing: -0.03em;
    text-transform: uppercase;
  }

  .title-accent {
    display: block;
    font-size: clamp(1.25rem, 3vw, 1.75rem);
    font-weight: 700;
    color: var(--color-accent);
    font-family: var(--font-mono);
    margin-top: var(--space-sm);
    letter-spacing: 0.05em;
  }

  .breadcrumb {
    font-family: var(--font-mono);
    font-size: 0.8rem;
    margin-bottom: var(--space-lg);
    color: var(--color-text-tertiary);
  }

  .breadcrumb a {
    color: var(--color-accent);
    text-decoration: none;
  }

  .breadcrumb a:hover {
    text-decoration: underline;
  }

  .breadcrumb-sep {
    margin: 0 0.5rem;
    color: var(--color-text-tertiary);
  }

  .hero-note {
    display: flex;
    gap: var(--space-md);
    align-items: baseline;
    margin-top: var(--space-lg);
    padding: var(--space-md) var(--space-lg);
    background: var(--color-bg-elevated);
    border: 1px solid var(--color-border);
    border-left: 3px solid var(--color-accent);
  }

  .hero-note-label {
    font-family: var(--font-mono);
    font-size: 0.7rem;
    font-weight: 700;
    color: var(--color-accent);
    letter-spacing: 0.1em;
    flex-shrink: 0;
  }

  .hero-note-text {
    font-size: 0.9rem;
    color: var(--color-text-secondary);
    line-height: 1.6;
  }

  /* ===== Quick Nav ===== */
  .quick-nav {
    padding: var(--space-lg) 0;
    background: var(--color-bg);
    border-bottom: 1px solid var(--color-border);
    position: sticky;
    top: 60px;
    z-index: 10;
  }

  .nav-strip {
    display: flex;
    gap: var(--space-sm);
    overflow-x: auto;
    scrollbar-width: none;
    -ms-overflow-style: none;
  }

  .nav-strip::-webkit-scrollbar {
    display: none;
  }

  .nav-chip {
    font-family: var(--font-mono);
    font-size: 0.75rem;
    padding: 0.5rem 1rem;
    background: var(--color-bg-secondary);
    border: 1px solid var(--color-border);
    color: var(--color-text-secondary);
    text-decoration: none;
    white-space: nowrap;
    transition: all 0.2s ease;
    letter-spacing: 0.02em;
  }

  .nav-chip:hover {
    border-color: var(--color-accent);
    color: var(--color-accent);
    background: var(--color-bg-elevated);
  }

  /* ===== Sections ===== */
  .docs-section {
    padding: var(--space-3xl) 0;
  }

  .section-alt {
    background: var(--color-bg-secondary);
  }

  .section-label {
    font-family: var(--font-mono);
    font-size: 0.75rem;
    color: var(--color-accent);
    letter-spacing: 0.2em;
    text-transform: uppercase;
    margin-bottom: var(--space-md);
  }

  .section-title {
    font-size: clamp(2rem, 5vw, 3rem);
    font-weight: 900;
    line-height: 1.1;
    text-transform: uppercase;
    letter-spacing: -0.02em;
    margin-bottom: var(--space-xl);
  }

  /* ===== Tool Cards ===== */
  .tools-list {
    display: flex;
    flex-direction: column;
    gap: var(--space-lg);
  }

  .tool-card {
    background: var(--color-bg);
    border: 1px solid var(--color-border);
    transition: border-color 0.2s ease;
    overflow: hidden;
  }

  .section-alt .tool-card {
    background: var(--color-bg-elevated);
  }

  .tool-card:hover {
    border-color: var(--color-accent);
  }

  .tool-featured {
    border-color: var(--color-accent);
    border-width: 2px;
  }

  .tool-header {
    padding: var(--space-lg) var(--space-xl);
    border-bottom: 1px solid var(--color-border);
  }

  .tool-title-row {
    display: flex;
    align-items: center;
    gap: var(--space-sm);
    flex-wrap: wrap;
    margin-bottom: var(--space-xs);
  }

  .tool-name {
    font-family: var(--font-mono);
    font-size: 1.1rem;
    font-weight: 700;
    color: var(--color-text);
  }

  .tool-sep {
    color: var(--color-text-tertiary);
    font-weight: 300;
  }

  .tool-tag {
    font-family: var(--font-mono);
    font-size: 0.6rem;
    padding: 0.2rem 0.5rem;
    background: var(--color-accent);
    color: var(--color-bg);
    font-weight: 700;
    letter-spacing: 0.08em;
    text-transform: uppercase;
  }

  .tool-tag-legacy {
    background: var(--color-text-tertiary);
  }

  .tool-tag-recommended {
    background: var(--color-accent-blue, #3b82f6);
  }

  .tag-danger {
    background: var(--color-accent-alt, #ef4444);
  }

  .tool-desc {
    color: var(--color-text-secondary);
    font-size: 0.95rem;
    line-height: 1.6;
    margin: 0;
  }

  .tool-aliases {
    font-family: var(--font-mono);
    font-size: 0.75rem;
    color: var(--color-text-tertiary);
    margin-top: var(--space-xs);
  }

  .tool-aliases code {
    color: var(--color-text-secondary);
    font-size: 0.75rem;
  }

  .tool-body {
    padding: var(--space-lg) var(--space-xl);
  }

  /* ===== Parameters ===== */
  .tool-params {
    margin-bottom: var(--space-lg);
  }

  .tool-params h4 {
    font-family: var(--font-mono);
    font-size: 0.75rem;
    font-weight: 700;
    text-transform: uppercase;
    color: var(--color-text-tertiary);
    letter-spacing: 0.1em;
    margin-bottom: var(--space-sm);
  }

  .no-params {
    font-family: var(--font-mono);
    font-size: 0.85rem;
    color: var(--color-text-tertiary);
    font-style: italic;
    margin: 0;
  }

  .params-table {
    width: 100%;
    border-collapse: collapse;
    font-size: 0.85rem;
  }

  .params-table thead th {
    font-family: var(--font-mono);
    font-size: 0.7rem;
    font-weight: 600;
    text-transform: uppercase;
    letter-spacing: 0.1em;
    color: var(--color-text-tertiary);
    text-align: left;
    padding: var(--space-xs) 0;
    border-bottom: 2px solid var(--color-border);
  }

  .params-table td {
    padding: var(--space-sm) 0;
    border-bottom: 1px solid var(--color-border);
    vertical-align: top;
  }

  .params-table tr:last-child td {
    border-bottom: none;
  }

  .params-table td:first-child {
    width: 130px;
    font-family: var(--font-mono);
    color: var(--color-accent);
    font-weight: 600;
  }

  .params-table td:nth-child(2) {
    width: 200px;
    font-size: 0.8rem;
    color: var(--color-text-secondary);
  }

  .params-table td:last-child {
    color: var(--color-text-secondary);
  }

  .type-badge {
    font-family: var(--font-mono);
    font-size: 0.6rem;
    padding: 0.15rem 0.35rem;
    font-weight: 700;
    letter-spacing: 0.05em;
    text-transform: uppercase;
    margin-right: 0.3rem;
  }

  .type-badge.req {
    background: var(--color-accent);
    color: var(--color-bg);
  }

  .type-badge.opt {
    background: var(--color-bg-elevated);
    border: 1px solid var(--color-border);
    color: var(--color-text-tertiary);
  }

  .patch-fields {
    font-size: 0.85rem;
    color: var(--color-text-tertiary);
    margin-top: var(--space-sm);
    padding: var(--space-sm);
    background: var(--color-bg-secondary);
  }

  .patch-fields code {
    color: var(--color-accent);
    font-size: 0.8rem;
  }

  /* ===== Examples ===== */
  .tool-example {
    margin-bottom: var(--space-lg);
  }

  .tool-example h4 {
    font-family: var(--font-mono);
    font-size: 0.75rem;
    font-weight: 700;
    text-transform: uppercase;
    color: var(--color-text-tertiary);
    letter-spacing: 0.1em;
    margin-bottom: var(--space-sm);
  }

  .tool-example pre {
    background: var(--color-bg-secondary);
    padding: var(--space-md);
    overflow-x: auto;
    margin: 0;
    border: 1px solid var(--color-border);
  }

  .section-alt .tool-example pre {
    background: var(--color-bg);
  }

  .tool-example code {
    font-family: var(--font-mono);
    font-size: 0.8rem;
    line-height: 1.7;
    color: var(--color-text-secondary);
  }

  .tool-examples-row {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: var(--space-lg);
    margin-bottom: var(--space-lg);
  }

  /* ===== Returns ===== */
  .tool-returns {
    margin-bottom: var(--space-lg);
  }

  .tool-returns h4 {
    font-family: var(--font-mono);
    font-size: 0.75rem;
    font-weight: 700;
    text-transform: uppercase;
    color: var(--color-text-tertiary);
    letter-spacing: 0.1em;
    margin-bottom: var(--space-sm);
  }

  .tool-returns p {
    color: var(--color-text-secondary);
    font-size: 0.9rem;
    line-height: 1.6;
    margin: 0;
  }

  .returns-fields {
    display: flex;
    flex-wrap: wrap;
    gap: var(--space-xs);
  }

  .returns-fields code {
    font-family: var(--font-mono);
    font-size: 0.75rem;
    padding: 0.25rem 0.5rem;
    background: var(--color-bg-secondary);
    border: 1px solid var(--color-border);
    color: var(--color-accent);
  }

  .section-alt .returns-fields code {
    background: var(--color-bg);
  }

  /* ===== Notes ===== */
  .tool-note {
    display: flex;
    gap: var(--space-sm);
    align-items: flex-start;
    padding: var(--space-md);
    background: var(--color-bg-secondary);
    border-left: 3px solid var(--color-accent);
  }

  .section-alt .tool-note {
    background: var(--color-bg);
  }

  .tool-note-warning {
    border-left-color: var(--color-accent-alt, #ef4444);
  }

  .note-icon {
    font-size: 1rem;
    flex-shrink: 0;
    line-height: 1.5;
  }

  .note-text {
    color: var(--color-text-secondary);
    font-size: 0.85rem;
    line-height: 1.5;
    margin: 0;
  }

  .note-text code {
    font-size: 0.8rem;
    color: var(--color-accent);
  }

  /* ===== Info Cards ===== */
  .info-card {
    background: var(--color-bg);
    border: 1px solid var(--color-border);
    padding: var(--space-xl);
  }

  .section-alt .info-card {
    background: var(--color-bg-elevated);
  }

  .info-text {
    font-size: 1.125rem;
    color: var(--color-text-secondary);
    margin-bottom: var(--space-xl);
    line-height: 1.7;
  }

  .info-text a {
    color: var(--color-accent);
    text-decoration: underline;
  }

  .info-text a:hover {
    color: var(--color-text);
  }

  .info-text-secondary {
    font-size: 0.95rem;
    color: var(--color-text-tertiary);
    font-style: italic;
    margin: 0;
  }

  .limits-row {
    display: flex;
    gap: var(--space-xl);
    margin-bottom: var(--space-xl);
  }

  .limit-box {
    display: flex;
    flex-direction: column;
    padding: var(--space-lg);
    background: var(--color-bg-secondary);
    border: 1px solid var(--color-border);
    min-width: 120px;
    text-align: center;
  }

  .limit-box .limit-value {
    font-family: var(--font-mono);
    font-size: 1.75rem;
    font-weight: 900;
    color: var(--color-accent);
    line-height: 1;
    margin-bottom: var(--space-xs);
  }

  .limit-box .limit-label {
    font-family: var(--font-mono);
    font-size: 0.7rem;
    color: var(--color-text-tertiary);
    text-transform: uppercase;
    letter-spacing: 0.1em;
  }

  /* ===== Path Options ===== */
  .path-options {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
    gap: var(--space-lg);
    margin-bottom: var(--space-xl);
  }

  .path-option {
    display: flex;
    gap: var(--space-md);
    align-items: flex-start;
  }

  .path-badge {
    font-family: var(--font-mono);
    font-size: 0.75rem;
    padding: 0.35rem 0.7rem;
    background: var(--color-bg-secondary);
    border: 1px solid var(--color-border);
    color: var(--color-accent);
    font-weight: 700;
    text-transform: uppercase;
    flex-shrink: 0;
  }

  .path-text {
    color: var(--color-text-secondary);
    font-size: 0.95rem;
    line-height: 1.6;
  }

  .path-text code {
    font-family: var(--font-mono);
    font-size: 0.85rem;
    color: var(--color-accent);
  }

  /* ===== Code Block ===== */
  .prompt-intro {
    max-width: 900px;
  }

  .code-block {
    background: var(--color-bg-secondary);
    border: 1px solid var(--color-border);
    margin-bottom: var(--space-lg);
  }

  .code-header {
    display: flex;
    justify-content: space-between;
    align-items: center;
    padding: var(--space-sm) var(--space-md);
    background: var(--color-bg-elevated);
    border-bottom: 1px solid var(--color-border);
  }

  .code-filename {
    font-family: var(--font-mono);
    font-size: 0.8rem;
    color: var(--color-text-secondary);
  }

  .code-lang {
    font-family: var(--font-mono);
    font-size: 0.7rem;
    padding: 0.2rem 0.5rem;
    background: var(--color-bg-secondary);
    color: var(--color-accent);
    text-transform: uppercase;
  }

  .code-block pre {
    padding: var(--space-md);
    margin: 0;
    overflow-x: auto;
  }

  .code-block code {
    font-family: var(--font-mono);
    font-size: 0.85rem;
    line-height: 1.7;
    color: var(--color-text-secondary);
  }

  /* ===== Responsive ===== */
  @media (max-width: 768px) {
    .tools-hero {
      min-height: auto;
      padding-top: calc(var(--space-2xl) + 60px);
    }

    .tool-header {
      padding: var(--space-md);
    }

    .tool-body {
      padding: var(--space-md);
    }

    .tool-examples-row {
      grid-template-columns: 1fr;
    }

    .limits-row {
      flex-direction: column;
      gap: var(--space-md);
    }

    .path-options {
      grid-template-columns: 1fr;
    }

    .nav-strip {
      padding-bottom: var(--space-sm);
    }

    .params-table td:nth-child(2) {
      width: auto;
    }
  }
</style>