From c9589ac0e06a7eecb5687c6d3930f7867c5f50d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stig-=C3=98rjan=20Smelror?= Date: Thu, 5 Feb 2026 18:22:58 +0100 Subject: [PATCH] Add a tools page --- docs/TOOL_CALLS.md | 550 +++++++++++++++++++++ src/pages/docs.astro | 86 ++++ src/pages/tools.astro | 1060 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 1696 insertions(+) create mode 100644 docs/TOOL_CALLS.md create mode 100644 src/pages/tools.astro diff --git a/docs/TOOL_CALLS.md b/docs/TOOL_CALLS.md new file mode 100644 index 0000000..8ea3755 --- /dev/null +++ b/docs/TOOL_CALLS.md @@ -0,0 +1,550 @@ +# Zaguán Blade Tool Calls Reference + +This document describes the regular tool calls that Zaguán Blade supports. These are the tools you can add to your Local AI system prompts to extend usability. + +> **Note:** This does not cover Blade-specific or ZLP (Zaguán Language Protocol) tools. These are standard file/editor tools for general AI coding assistance. + +--- + +## File Operations + +### `read_file` + +Read the complete contents of a file. + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | File path (relative to workspace or absolute) | + +**Aliases:** `file_path`, `filepath`, `filename` + +**Example:** +```json +{ + "path": "src/main.rs" +} +``` + +--- + +### `read_file_range` + +Read a specific line range from a file with optional context. + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | File path | +| `start_line` | integer | No | Start line (1-indexed, default: 1) | +| `end_line` | integer | No | End line (1-indexed, default: end of file) | +| `context_lines` | integer | No | Extra context lines before/after range (default: 0) | + +**Example:** +```json +{ + "path": "src/lib.rs", + "start_line": 50, + "end_line": 100, + "context_lines": 3 +} +``` + +--- + +### `write_file` / `create_file` + +Write content to a file. Creates parent directories if needed. + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | File path | +| `content` | string | Yes | Content to write | + +**Aliases for content:** `contents`, `text`, `data` + +**Example:** +```json +{ + "path": "src/new_module.rs", + "content": "pub fn hello() {\n println!(\"Hello!\");\n}\n" +} +``` + +--- + +### `edit_file` + +Apply a search/replace edit to a file (legacy tool). + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | File path | +| `old_content` | string | Yes | Text to find | +| `new_content` | string | Yes | Replacement text | + +**Aliases:** `old`/`from` for old_content, `new`/`to` for new_content + +**Example:** +```json +{ + "path": "src/main.rs", + "old_content": "fn old_function()", + "new_content": "fn new_function()" +} +``` + +--- + +### `apply_edit` / `apply_patch` + +Apply search/replace edits with robust fuzzy matching. Supports both single patches and atomic multi-patch operations. + +**Single Patch Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | File path | +| `old_text` | string | Yes | Text to find and replace | +| `new_text` | string | Yes | Replacement text | + +**Multi-Patch Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | File path | +| `patches` | array | Yes | Array of patch objects | + +Each patch object contains: +- `old_text` (string): Text to find +- `new_text` (string): Replacement text +- `start_line` (integer, optional): Hint for disambiguation +- `end_line` (integer, optional): Hint for disambiguation + +**Single Patch Example:** +```json +{ + "path": "src/lib.rs", + "old_text": "let x = 5;", + "new_text": "let x = 10;" +} +``` + +**Multi-Patch Example:** +```json +{ + "path": "src/lib.rs", + "patches": [ + {"old_text": "fn foo()", "new_text": "fn bar()"}, + {"old_text": "let a = 1;", "new_text": "let a = 2;"} + ] +} +``` + +> **Note:** Multi-patch operations are atomic—all patches are validated before any are applied. If any patch fails, no changes are made. + +--- + +### `delete_file` + +Delete a file or directory. + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | Path to delete | +| `recursive` | boolean | No | Required for directories (default: false) | + +**Example:** +```json +{ + "path": "temp/old_file.txt" +} +``` + +--- + +### `move_file` + +Move or rename a file. + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `source` | string | Yes | Source path | +| `destination` | string | Yes | Destination path | + +**Example:** +```json +{ + "source": "src/old_name.rs", + "destination": "src/new_name.rs" +} +``` + +--- + +### `copy_file` + +Copy a file or directory (recursive for directories). + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `source` | string | Yes | Source path | +| `destination` | string | Yes | Destination path | + +**Example:** +```json +{ + "source": "templates/base.html", + "destination": "src/templates/base.html" +} +``` + +--- + +### `get_file_info` + +Get metadata about a file or directory. + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | Path to inspect | + +**Returns:** JSON with `path`, `size`, `is_directory`, `is_file`, `modified`, `readonly` + +**Example:** +```json +{ + "path": "Cargo.toml" +} +``` + +--- + +### `create_directory` + +Create a directory (and parent directories if needed). + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | Directory path to create | + +**Example:** +```json +{ + "path": "src/modules/new_feature" +} +``` + +--- + +## Directory & Search Tools + +### `list_directory` / `list_dir` + +List directory contents with tree view. + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | No | Directory path (default: ".") | +| `max_depth` | integer | No | Max traversal depth (default: 1) | + +**Aliases:** `dir`, `directory` + +**Example:** +```json +{ + "path": "src", + "max_depth": 2 +} +``` + +--- + +### `get_workspace_structure` + +Get a tree view of the workspace structure. + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | No | Starting path (default: ".") | +| `depth` | integer | No | Max depth (default: 2) | +| `limit` | integer | No | Max entries (default: 50, max: 200) | + +**Example:** +```json +{ + "path": ".", + "depth": 3, + "limit": 100 +} +``` + +> **Note:** Automatically ignores common directories like `node_modules`, `target`, `.git`, `__pycache__`, etc. + +--- + +### `find_files` + +Find files by name pattern (substring match). + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `pattern` | string | Yes | Substring to match in filenames | +| `path` | string | No | Starting path (default: workspace root) | +| `max_depth` | integer | No | Max search depth | + +**Example:** +```json +{ + "pattern": "test", + "path": "src", + "max_depth": 5 +} +``` + +--- + +### `find_files_glob` / `glob` + +Find files using glob patterns. + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `pattern` | string | Yes | Glob pattern (e.g., `**/*.rs`) | +| `path` | string | No | Base path for search | +| `case_sensitive` | boolean | No | Case-sensitive matching (default: false) | + +**Example:** +```json +{ + "pattern": "**/*.tsx", + "path": "src" +} +``` + +--- + +### `grep_search` / `rg` + +Search file contents using regex patterns. + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `pattern` | string | Yes | Regex pattern to search | +| `path` | string | No | Directory to search (default: ".") | + +**Aliases for pattern:** `query`, `regex` + +**Example:** +```json +{ + "pattern": "fn\\s+main", + "path": "src" +} +``` + +**Returns:** Matches in format `filepath:line_number:line_content` + +--- + +### `codebase_search` + +Search codebase with context lines around matches. + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `query` | string | Yes | Regex pattern to search | +| `file_pattern` | string | No | Filter files (e.g., `*.rs,*.toml`) | +| `max_results` | integer | No | Maximum results (default: 50) | + +**Example:** +```json +{ + "query": "struct.*Config", + "file_pattern": "*.rs", + "max_results": 20 +} +``` + +**Returns:** Matches with 2 lines of context before and after. + +--- + +## Editor Interaction Tools + +### `get_editor_state` + +Get current editor context including active file, cursor position, and open files. + +**Parameters:** None + +**Returns:** JSON with: +- `active_file`: Currently focused file +- `open_files`: List of open file paths +- `active_tab_index`: Index of active tab +- `cursor_line`, `cursor_column`: Cursor position +- `selection_start_line`, `selection_end_line`: Selection range + +--- + +### `open_file` + +Open a file in the editor. + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | File path to open | +| `line` | integer | No | Line number to jump to | + +**Example:** +```json +{ + "path": "src/main.rs", + "line": 42 +} +``` + +--- + +### `goto_line` + +Navigate to a specific line in the active file. + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `line` | integer | Yes | Line number (1-indexed) | +| `column` | integer | No | Column number | + +**Example:** +```json +{ + "line": 100, + "column": 15 +} +``` + +--- + +### `get_selection` + +Get the currently selected text in the editor. + +**Parameters:** None + +**Returns:** The selected text content. + +--- + +### `replace_selection` + +Replace the current selection with new content. + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `content` | string | Yes | Replacement content | + +**Example:** +```json +{ + "content": "new replacement text" +} +``` + +--- + +### `insert_at_cursor` + +Insert content at the current cursor position. + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `content` | string | Yes | Content to insert | + +**Example:** +```json +{ + "content": "// TODO: implement this\n" +} +``` + +--- + +## Command Execution + +### `run_command` + +Execute a shell command (requires user approval). + +**Parameters:** +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `command` | string | Yes | Shell command to execute | +| `cwd` | string | Yes | Working directory | + +**Example:** +```json +{ + "command": "cargo build --release", + "cwd": "." +} +``` + +> **Note:** This tool requires user confirmation before execution for safety. + +--- + +## Tool Result Handling + +Tool results are automatically truncated if they exceed limits: +- **Max size:** 50KB +- **Max lines:** 2000 + +When truncated, the first 100 lines and last 50 lines are shown with a truncation message. + +--- + +## Path Resolution + +All paths can be: +- **Relative:** Resolved from workspace root (e.g., `src/main.rs`) +- **Absolute:** Used as-is (must be within workspace) + +Paths outside the workspace are rejected for security. + +--- + +## Adding Tools to Your AI System Prompt + +To use these tools with a local AI, include the tool definitions in your system prompt. Example format: + +``` +You have access to the following tools: + +- read_file: Read file contents. Args: {"path": "string"} +- write_file: Write to file. Args: {"path": "string", "content": "string"} +- grep_search: Search with regex. Args: {"pattern": "string", "path": "string"} +- apply_edit: Edit file. Args: {"path": "string", "old_text": "string", "new_text": "string"} +... + +To use a tool, respond with: + +{"name": "tool_name", "arguments": {...}} + +``` + +The exact format depends on your AI provider's tool calling conventions. diff --git a/src/pages/docs.astro b/src/pages/docs.astro index c834d91..893a212 100644 --- a/src/pages/docs.astro +++ b/src/pages/docs.astro @@ -458,6 +458,31 @@ import BaseLayout from '../layouts/BaseLayout.astro'; + +
+
+
[012] TOOL_CALLS_REFERENCE
+

Tool Calls Reference

+ +
+

+ When creating custom system prompts for Local AI models, you'll need to include definitions for the tool calls Zaguán Blade supports. This reference document describes all available tools with their parameters and usage examples. +

+ +
+ + 📖 + + View Complete Tool Calls Reference +

Full documentation of all available tool calls for Local AI system prompts

+ + → + +
+
+
+
+
@@ -1390,6 +1415,67 @@ import BaseLayout from '../layouts/BaseLayout.astro'; color: var(--color-accent) !important; } + /* Tool Calls Section */ + .tool-calls-cta { + margin-top: var(--space-xl); + } + + .tool-calls-link { + display: flex; + align-items: center; + gap: var(--space-lg); + padding: var(--space-xl); + background: var(--color-bg); + border: 2px solid var(--color-accent); + border-radius: var(--border-radius); + text-decoration: none; + transition: all 0.3s ease; + } + + .tool-calls-link:hover { + background: var(--color-bg-elevated); + transform: translateY(-4px); + } + + .tool-calls-icon { + font-size: 2.5rem; + flex-shrink: 0; + } + + .tool-calls-text { + flex: 1; + } + + .tool-calls-link strong { + display: block; + font-size: 1.25rem; + font-weight: 700; + color: var(--color-text); + margin-bottom: var(--space-xs); + text-transform: uppercase; + } + + .tool-calls-subtext { + color: var(--color-text-secondary); + font-size: 0.95rem; + margin: 0; + line-height: 1.5; + } + + .tool-calls-arrow { + font-size: 1.5rem; + color: var(--color-accent); + transition: transform 0.3s ease; + } + + .tool-calls-link:hover .tool-calls-arrow { + transform: translateX(4px); + } + + .tool-calls-link:hover { + border-color: var(--color-accent); + } + /* Responsive */ @media (max-width: 768px) { .docs-hero { diff --git a/src/pages/tools.astro b/src/pages/tools.astro new file mode 100644 index 0000000..a836195 --- /dev/null +++ b/src/pages/tools.astro @@ -0,0 +1,1060 @@ +--- +import BaseLayout from '../layouts/BaseLayout.astro'; +--- + + +
+ +
+
+
+
// TOOL_CALLS.md
+

+ TOOL CALLS + REFERENCE_ +

+

+ Complete reference for all tool calls available in Zaguán Blade. + These are the standard tools you can add to your Local AI system prompts. +

+
+
+
+ + +
+
+
[001] INTRODUCTION
+

Overview

+ +
+

+ This document describes the regular tool calls that Zaguán Blade supports. These are the tools you can add to your Local AI system prompts to extend usability. +

+ +
+ ℹ️ +

+ Note: This does not cover Blade-specific or ZLP (Zaguán Language Protocol) tools. These are standard file/editor tools for general AI coding assistance. +

+
+
+
+
+ + +
+
+
[002] FILE_OPERATIONS
+

File Operations

+ +
+ +
+
+ read_file + FILE_READ +
+

Read the complete contents of a file.

+ +
+

Parameters

+ + +
pathstring (required)File path (relative to workspace or absolute)
+
+ +
+

Example

+ 
{ "path": "src/main.rs" }
+
+
+ + +
+
+ read_file_range + FILE_READ +
+

Read a specific line range from a file with optional context.

+ +
+

Parameters

+ + + + + +
pathstring (required)File path
start_lineinteger (optional)Start line (1-indexed, default: 1)
end_lineinteger (optional)End line (1-indexed, default: end of file)
context_linesinteger (optional)Extra context lines before/after range (default: 0)
+
+ +
+

Example

+ 
{
+  "path": "src/lib.rs",
+  "start_line": 50,
+  "end_line": 100,
+  "context_lines": 3
+}
+
+
+ + +
+
+ write_file + FILE_WRITE +
+

Write content to a file. Creates parent directories if needed.

+ +
+

Parameters

+ + + +
pathstring (required)File path
contentstring (required)Content to write
+
+ +
+

Example

+ 
{
+  "path": "src/new_module.rs",
+  "content": "pub fn hello() {\n    println!(\"Hello!\");\n}\n"
+}
+
+
+ + +
+
+ apply_patch + FILE_EDIT +
+

Apply search/replace edits with robust fuzzy matching. Supports both single patches and atomic multi-patch operations.

+ +
+

Single Patch Parameters

+ + + + +
pathstring (required)File path
old_textstring (required)Text to find and replace
new_textstring (required)Replacement text
+
+ +
+

Single Patch Example

+ 
{
+  "path": "src/lib.rs",
+  "old_text": "let x = 5;",
+  "new_text": "let x = 10;"
+}
+
+ +
+

Multi-Patch Example

+ 
{
+  "path": "src/lib.rs",
+  "patches": [
+    {"old_text": "fn foo()", "new_text": "fn bar()"},
+    {"old_text": "let a = 1;", "new_text": "let a = 2;"}
+  ]
+}
+
+
+ + +
+
+ delete_file + FILE_DELETE +
+

Delete a file or directory.

+ +
+

Parameters

+ + + +
pathstring (required)Path to delete
recursiveboolean (optional)Required for directories (default: false)
+
+
+ + +
+
+ move_file + FILE_MOVE +
+

Move or rename a file.

+ +
+

Parameters

+ + + +
sourcestring (required)Source path
destinationstring (required)Destination path
+
+
+ + +
+
+ copy_file + FILE_COPY +
+

Copy a file or directory (recursive for directories).

+ +
+

Parameters

+ + + +
sourcestring (required)Source path
destinationstring (required)Destination path
+
+
+ + +
+
+ get_file_info + FILE_INFO +
+

Get metadata about a file or directory.

+ +
+

Parameters

+ + +
pathstring (required)Path to inspect
+
+ +
+

Returns

+

JSON with path, size, is_directory, is_file, modified, readonly

+
+
+ + +
+
+ create_directory + FILE_CREATE +
+

Create a directory (and parent directories if needed).

+ +
+

Parameters

+ + +
pathstring (required)Directory path to create
+
+
+
+
+
+ + + + + +
+
+
[004] EDITOR_INTERACTION
+

Editor Interaction Tools

+ +
+ +
+
+ get_editor_state + EDITOR_INFO +
+

Get current editor context including active file, cursor position, and open files.

+ +
+

Parameters

+

None

+
+ +
+

Returns

+

JSON with: active_file, open_files, active_tab_index, cursor_line, cursor_column, selection_start_line, selection_end_line

+
+
+ + +
+
+ open_file + EDITOR_CONTROL +
+

Open a file in the editor.

+ +
+

Parameters

+ + + +
pathstring (required)File path to open
lineinteger (optional)Line number to jump to
+
+
+ + +
+
+ goto_line + EDITOR_CONTROL +
+

Navigate to a specific line in the active file.

+ +
+

Parameters

+ + + +
lineinteger (required)Line number (1-indexed)
columninteger (optional)Column number
+
+
+ + +
+
+ get_selection + EDITOR_SELECTION +
+

Get the currently selected text in the editor.

+ +
+

Parameters

+

None

+
+ +
+

Returns

+

The selected text content.

+
+
+ + +
+
+ replace_selection + EDITOR_EDIT +
+

Replace the current selection with new content.

+ +
+

Parameters

+ + +
contentstring (required)Replacement content
+
+
+ + +
+
+ insert_at_cursor + EDITOR_EDIT +
+

Insert content at the current cursor position.

+ +
+

Parameters

+ + +
contentstring (required)Content to insert
+
+
+
+
+
+ + +
+
+
[005] COMMAND_EXECUTION
+

Command Execution

+ +
+ +
+
+ run_command + TERMINAL +
+

Execute a shell command (requires user approval).

+ +
+

Parameters

+ + + +
commandstring (required)Shell command to execute
cwdstring (required)Working directory
+
+ +
+

Example

+ 
{
+  "command": "cargo build --release",
+  "cwd": "."
+}
+
+ +
+ ⚠️ +

This tool requires user confirmation before execution for safety.

+
+
+
+
+
+ + +
+
+
[006] TOOL_RESULTS
+

Tool Result Handling

+ +
+

Truncation

+

Tool results are automatically truncated if they exceed limits:

+ +
+
+ Max size: + 50KB +
+
+ Max lines: + 2000 +
+
+ +

When truncated, the first 100 lines and last 50 lines are shown with a truncation message.

+
+
+
+ + +
+
+
[007] PATH_RESOLUTION
+

Path Resolution

+ +
+

All paths can be:

+ +
+
+ Relative + Resolved from workspace root (e.g., src/main.rs) +
+
+ Absolute + Used as-is (must be within workspace) +
+
+ +
+ ⚠️ +

Paths outside the workspace are rejected for security.

+
+
+
+
+ + +
+
+
[008] SYSTEM_PROMPT
+

Adding Tools to Your AI System Prompt

+ +
+

+ To use these tools with a local AI, include the tool definitions in your system prompt. Example format: +

+ +
+
+ System Prompt + markdown +
+ 
You have access to the following tools:
+
+- read_file: Read file contents. Args: {"path": "string"}
+- write_file: Write to file. Args: {"path": "string", "content": "string"}
+- grep_search: Search with regex. Args: {"pattern": "string", "path": "string"}
+- apply_edit: Edit file. Args: {"path": "string", "old_text": "string", "new_text": "string"}
+...
+
+To use a tool, respond with:
+
+{"name": "tool_name", "arguments": {...}}
+
+
+ +

+ The exact format depends on your AI provider's tool calling conventions. +

+
+
+
+
+ + +