@oh-my-pi/pi-coding-agent 6.9.69 → 8.0.0

package/src/prompts/tools/fetch.md

@@ -0,0 +1,16 @@
+# Fetch
+
+Retrieves content from a URL and returns it in a clean, readable format.
+
+<instruction>
+- Extract information from web pages (documentation, articles, API references)
+- Analyze GitHub issues, PRs, or repository content
+- Retrieve from Stack Overflow, Wikipedia, Reddit, NPM, arXiv, technical blogs
+- Access RSS/Atom feeds or JSON endpoints
+- Read PDF or DOCX files hosted at a URL
+- Use `raw: true` for untouched HTML or debugging
+</instruction>
+
+<output>
+Returns processed, readable content extracted from the URL. HTML is transformed to remove navigation, ads, and boilerplate. PDF and DOCX files are converted to text. JSON endpoints return formatted JSON. With `raw: true`, returns untransformed HTML.
+</output>

package/src/prompts/tools/find.md

@@ -1,6 +1,16 @@
-- Fast file pattern matching tool that works with any codebase size
+# Find
+
+Fast file pattern matching that works with any codebase size.
+
+<instruction>
 - Supports glob patterns like "**/*.js" or "src/**/*.ts"
-- Returns matching file paths sorted by modification time
-- Use this tool when you need to find files by name patterns
-- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead
-- You can call multiple tools in a single response. It is always better to speculatively perform multiple searches in parallel if they are potentially useful.
+- Speculatively perform multiple searches in parallel when potentially useful
+</instruction>
+
+<output>
+Matching file paths sorted by modification time (most recent first). Results truncated at 1000 entries or 50KB.
+</output>
+
+<avoid>
+Open-ended searches requiring multiple rounds of globbing and grepping — use Task tool instead.
+</avoid>

package/src/prompts/tools/gemini-image.md

@@ -1,8 +1,23 @@
-Generate or edit images using Gemini image models directly or via OpenRouter.
+# Gemini Image
 
-Provide a text prompt and optional input images. Use response modalities to request image-only output,
-set aspect ratio or image size, and choose the model explicitly when needed.
+Generate or edit images using Gemini image models.
 
-Prompt tips:
-- Describe subject, composition, style, and lighting in full sentences.
-- For edits, reference the input image and specify the exact changes.
+<instruction>
+Provide structured parameters for best results. The tool assembles them into an optimized prompt.
+
+When using multiple `input_images`, describe each image's role in the `subject` or `scene` field:
+- "Use Image 1 for the character's face and outfit, Image 2 for the pose, Image 3 for the background environment"
+- "Match the color palette from Image 1, apply the lighting style from Image 2"
+</instruction>
+
+<output>
+Returns the generated image saved to disk. The response includes the file path where the image was written.
+</output>
+
+<important>
+- For photoreal: add "ultra-detailed, realistic, natural skin texture" to style
+- For posters/cards: use 9:16 aspect ratio with negative space for text placement
+- For iteration: use `changes` to make targeted adjustments rather than regenerating from scratch
+- For text: add "sharp, legible, correctly spelled" for important text; keep text short
+- For diagrams: include "scientifically accurate" in style and provide facts explicitly
+</important>

package/src/prompts/tools/grep.md

@@ -1,12 +1,28 @@
-A powerful search tool built on ripgrep
-
-Usage:
-  - ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command. The Grep tool has been optimized for correct permissions and access.
-  - Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")
-  - Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
-  - Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts
-  - Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping (use `interface\\{\\}` to find `interface{}` in Go code)
-  - Multiline matching: By default patterns match within single lines only. For cross-line patterns like `struct \\{[\\s\\S]*?field`, use `multiline: true`
-
-Important:
-  - ALWAYS Use Task tool with explore subagent over this for open-ended searches requiring multiple rounds
+# Grep
+
+A powerful search tool built on ripgrep.
+
+<instruction>
+- Supports full regex syntax (e.g., `log.*Error`, `function\\s+\\w+`)
+- Filter files with `glob` (e.g., `*.js`, `**/*.tsx`) or `type` (e.g., `js`, `py`, `rust`)
+- Pattern syntax uses ripgrep—literal braces need escaping (`interface\\{\\}` to find `interface{}` in Go)
+- For cross-line patterns like `struct \\{[\\s\\S]*?field`, use `multiline: true`
+</instruction>
+
+<output>
+Results depend on `output_mode`:
+- `content`: Matching lines with file paths and line numbers
+- `files_with_matches`: File paths only (one per line)
+- `count`: Match counts per file
+
+In `content` mode, truncated at 100 matches by default (configurable via `limit`).
+For `files_with_matches` and `count` modes, use `head_limit` to truncate results.
+</output>
+
+<critical>
+- ALWAYS use Grep for search tasks—NEVER invoke `grep` or `rg` via Bash. This tool has correct permissions and access.
+</critical>
+
+<avoid>
+- Open-ended searches requiring multiple rounds—use Task tool with explore subagent instead
+</avoid>

package/src/prompts/tools/lsp.md

@@ -1,14 +1,35 @@
-Interact with Language Server Protocol (LSP) servers to get code intelligence features.
-
-Standard operations:
-- diagnostics: Get errors/warnings for a file
-- workspace_diagnostics: Check entire project for errors (uses tsc, cargo check, go build, etc.)
-- definition: Go to symbol definition
-- references: Find all references to a symbol
-- hover: Get type info and documentation
-- symbols: List symbols in a file (functions, classes, etc.)
-- workspace_symbols: Search for symbols across the project
-- rename: Rename a symbol across the codebase
-- actions: List and apply code actions (quick fixes, refactors)
-- incoming_calls: Find all callers of a function
-- outgoing_calls: Find all functions called by a function
+# LSP
+
+Interact with Language Server Protocol servers for code intelligence.
+
+<operations>
+- `diagnostics`: Get errors/warnings for a file
+- `workspace_diagnostics`: Check entire project (uses tsc, cargo check, go build, etc.)
+- `definition`: Go to symbol definition
+- `references`: Find all references to a symbol
+- `hover`: Get type info and documentation
+- `symbols`: List symbols in a file (functions, classes, etc.)
+- `workspace_symbols`: Search for symbols across the project
+- `rename`: Rename a symbol across the codebase
+- `actions`: List and apply code actions (quick fixes, refactors)
+- `incoming_calls`: Find all callers of a function
+- `outgoing_calls`: Find all functions called by a function
+</operations>
+
+<output>
+Returns vary by operation:
+- `diagnostics`/`workspace_diagnostics`: List of errors/warnings with file, line, severity, message
+- `definition`: File path and position of the definition
+- `references`: List of locations (file + position) where symbol is used
+- `hover`: Type signature and documentation text
+- `symbols`/`workspace_symbols`: List of symbol names, kinds, and locations
+- `rename`: Confirmation of changes made across files
+- `actions`: List of available code actions; when applied, returns the result
+- `incoming_calls`/`outgoing_calls`: Call hierarchy with caller/callee locations
+</output>
+
+<important>
+- Requires a running LSP server for the target language
+- Some operations require the file to be saved to disk
+- `workspace_diagnostics` may be slow on large projects
+</important>

package/src/prompts/tools/patch.md

@@ -1,15 +1,29 @@
-Performs patch operations on a file given a diff.
-This is your primary tool for making changes to existing files.
+# Edit
 
-<critical>
-- Always read the target file before editing.
-- Copy anchors + context lines verbatim (including whitespace).
-- Output the clean patch format below.
-</critical>
+Performs patch operations on a file given a diff. Primary tool for modifying existing files.
+
+<instruction>
+**Hunk Headers:**
+- `@@` — bare header when context lines are already unique
+- `@@ $ANCHOR` — anchor must be copied verbatim from the file (full line or unique substring)
+
+**Anchor Selection Algorithm:**
+1. If surrounding context lines are already unique, use bare `@@`
+2. Otherwise choose a highly specific anchor copied from the file:
+   - full function signature line
+   - class declaration line
+   - unique string literal / error message
+   - config key with uncommon name
+3. If "Found multiple matches" error: add more context lines, use multiple hunks with separate anchors, or use a longer anchor substring
+
+**Context Lines:**
+- Include enough ` `-prefixed lines to make match unique (usually 2–8 total)
+- Must exist in the file exactly as written (preserve indentation/trailing spaces)
+</instruction>
 
 <parameters>
 ```ts
-type T = 
+type T =
    // Diff is one or more hunks, within the same file.
    // - Each hunk begins with "@@" (optionally with an anchor).
    // - Each hunk body contains only lines starting with: ' ' | '+' | '-'.
@@ -24,40 +38,18 @@ type T =
 ```
 </parameters>
 
-<hunk_header>
-Allowed:
-- `@@`
-- `@@ $ANCHOR`
+<output>
+Returns success/failure status. On failure, returns error message indicating:
+- "Found multiple matches" — anchor/context not unique enough
+- "No match found" — context lines don't exist in file (wrong content or stale read)
+- Syntax errors in diff format
+</output>
 
-ANCHOR RULES:
-- `$ANCHOR` MUST be copied verbatim from the file as either:
-  - a full existing line, OR
-  - a unique substring of a single existing line.
-- NEVER use it as a comment:
-  - line numbers / ranges: `line 207`, `lines 26-37`
-  - location labels: `top of file`, `start`, `near imports`
-  - placeholders: `@@ @@`, `...`
-</hunk_header>
-
-<anchor_selection>
-ANCHOR SELECTION ALGORITHM (use in this order):
-1) If the surrounding context lines are already unique in the file, use bare `@@`.
-2) Else choose an anchor that is highly specific and stable, copied from the file, e.g.:
-   - full function signature line
-   - class declaration line
-   - a unique string literal / error message
-   - a config key with uncommon name
-3) If you get "Found multiple matches", escalate by:
-   - adding more context lines, OR
-   - using multiple hunks with separate nearby anchors, OR
-   - using a more specific anchor substring (longer, includes identifiers).
-NEVER use generic anchors like `import`, `export`, `describe`, `function`, `const`.
-</anchor_selection>
-
-<context_rules>
-- Include enough context lines (' ' prefixed) to make the match unique (usually 2–8 total).
-- Context lines must exist in the file exactly as written; preserve indentation/trailing spaces.
-</context_rules>
+<critical>
+- Always read the target file before editing
+- Copy anchors and context lines verbatim (including whitespace)
+- Never use anchors as comments (no line numbers, location labels, or placeholders like `@@ @@`)
+</critical>
 
 <example name="create">
 edit {"path":"hello.txt","op":"create","diff":"Hello\n"}
@@ -74,3 +66,9 @@ edit {"path":"src/app.py","op":"update","rename":"src/main.py","diff":"@@\n ...\
 <example name="delete">
 edit {"path":"obsolete.txt","op":"delete"}
 </example>
+
+<avoid>
+- Generic anchors: `import`, `export`, `describe`, `function`, `const`
+- Anchor comments: `line 207`, `top of file`, `near imports`, `...`
+- Editing without reading the file first (causes stale context errors)
+</avoid>

package/src/prompts/tools/python.md

@@ -1,7 +1,8 @@
-Executes Python cells sequentially in a persistent IPython kernel.
+# Python
 
-## How to use (REPL discipline)
+Executes Python cells sequentially in a persistent IPython kernel.
 
+<instruction>
 The kernel persists between calls and between cells. **Imports, variables, and functions survive.** Use this.
 
 **Work incrementally:**
@@ -15,64 +16,9 @@ The kernel persists between calls and between cells. **Imports, variables, and f
 - Earlier cells already ran—their state persists in the kernel
 - Resubmit with only the fixed cell (or the fixed cell + remaining cells)
 - Do NOT rewrite working cells or re-import modules
+</instruction>
 
-**Anti-patterns to avoid:**
-- Putting everything in one giant cell
-- Re-importing modules you already imported
-- Rewriting working code when only one part failed
-- Large functions that are hard to debug piece by piece
-
-```python
-# BAD: One giant cell
-cells: [{
-    "title": "all-in-one",
-    "code": "import json\nfrom pathlib import Path\ndef process_all_files():\n    # 50 lines...\n    pass\nresult = process_all_files()"
-}]
-
-# GOOD: Multiple small cells
-cells: [
-    {"title": "imports", "code": "import json\nfrom pathlib import Path"},
-    {"title": "parse helper", "code": "def parse_config(path):\n    return json.loads(Path(path).read_text())"},
-    {"title": "test helper", "code": "parse_config('config.json')"},
-    {"title": "use helper", "code": "configs = [parse_config(p) for p in Path('.').glob('*.json')]"}
-]
-```
-
-## When to use Python
-
-**Use Python for user-facing operations:**
-- Displaying, concatenating, or merging files → `cat(*paths)`
-- Batch transformations across files → `batch(paths, fn)`, `rsed()`
-- Formatted output, tables, summaries
-- Any loop, conditional, or multi-step logic
-- Anything you'd write a bash script for
-
-**Use specialized tools for YOUR reconnaissance:**
-- Reading to understand code → Read tool
-- Searching to locate something → Grep tool
-- Finding files to identify targets → Find tool
-
-The distinction: Read/Grep/Find gather info for *your* decisions. Python executes *the user's* request.
-
-**Prefer Python over bash for:**
-- Loops and iteration → Python for-loops, not bash for/while
-- Text processing → `sed()`, `cols()`, `sort_lines()`, not sed/awk/cut
-- File operations → prelude helpers, not mv/cp/rm commands
-- Conditionals → Python if/else, not bash [[ ]]
-
-**Shell commands:** Use `sh()` or `run()`, never raw `subprocess`:
-```python
-# Good
-sh("bun run check")
-run("cargo build --release")
-
-# Bad - never use subprocess directly
-import subprocess
-subprocess.run(["bun", "run", "check"], ...)
-```
-
-## Prelude helpers
-
+<prelude>
 All helpers auto-print results and return values for chaining.
 
 {{#if categories.length}}
@@ -84,14 +30,49 @@ All helpers auto-print results and return values for chaining.
     {{docstring}}
 {{/each}}
 ```
-
 {{/each}}
 {{else}}
 (Documentation unavailable — Python kernel failed to start)
 {{/if}}
+</prelude>
 
-## Examples
+<output>
+Output streams in real time, truncated after 100KB.
+If output is truncated, full output is stored under $ARTIFACTS and referenced as `artifact://<id>` in metadata.
 
+The user sees output like a Jupyter notebook—rich displays are fully rendered:
+- `display(JSON(data))` → interactive JSON tree
+- `display(HTML(...))` → rendered HTML
+- `display(Markdown(...))` → formatted markdown
+- `plt.show()` → inline figures
+
+**You will see object repr** (e.g., `<IPython.core.display.JSON object>`) **but the user sees the rendered output.** Trust that `display()` calls work correctly—do not assume the user sees only the repr.
+</output>
+
+<important>
+- Kernel persists for the session by default; per-call mode uses a fresh kernel each call
+- Use `reset: true` to clear state when session mode is active
+</important>
+
+<critical>
+- Use `plt.show()` to display figures
+- Use `display()` from IPython.display for rich output (HTML, Markdown, images, etc.)
+- Use `sh()` or `run()` for shell commands, never raw `subprocess`
+</critical>
+
+<example name="good">
+```python
+# Multiple small cells
+cells: [
+    {"title": "imports", "code": "import json\nfrom pathlib import Path"},
+    {"title": "parse helper", "code": "def parse_config(path):\n    return json.loads(Path(path).read_text())"},
+    {"title": "test helper", "code": "parse_config('config.json')"},
+    {"title": "use helper", "code": "configs = [parse_config(p) for p in Path('.').glob('*.json')]"}
+]
+```
+</example>
+
+<example name="prelude-helpers">
 ```python
 # Concatenate all markdown files in docs/
 cat(*find("*.md", "docs"))
@@ -108,22 +89,23 @@ sort_lines(read("data.txt"), unique=True)
 # Extract columns 0 and 2 from TSV
 cols(read("data.tsv"), 0, 2, sep="\t")
 ```
+</example>
 
-## Notes
-
-- Code executes as IPython cells; users see the full cell output (including rendered figures, tables, etc.)
-- Kernel persists for the session by default; per-call mode uses a fresh kernel each call. Use `reset: true` to clear state when session mode is active
-- Use `cwd` parameter instead of `os.chdir()` in tool call
-- Use `plt.show()` to display figures
-- Use `display()` from IPython.display for rich output (HTML, Markdown, images, etc.)
-- Output streams in real time, truncated after 50KB
-
-## Rich output rendering
+<example name="shell-commands">
+```python
+# Good
+sh("bun run check")
+run("cargo build --release")
 
-The user sees output like a Jupyter notebook—rich displays are fully rendered:
-- `display(JSON(data))` → interactive JSON tree
-- `display(HTML(...))` → rendered HTML
-- `display(Markdown(...))` → formatted markdown
-- `plt.show()` → inline figures
+# Bad - never use subprocess directly
+import subprocess
+subprocess.run(["bun", "run", "check"], ...)
+```
+</example>
 
-**You will see object repr** (e.g., `<IPython.core.display.JSON object>`) **but the user sees the rendered output.** Trust that `display()` calls work correctly—do not assume the user sees only the repr.
+<avoid>
+- Putting everything in one giant cell
+- Re-importing modules you already imported
+- Rewriting working cells when only one part failed
+- Large functions that are hard to debug piece by piece
+</avoid>

package/src/prompts/tools/read.md

@@ -1,25 +1,26 @@
-Reads a file from the local filesystem. You can access any file directly by using this tool.
-Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+# Read
 
-Usage:
-- By default, it reads up to {{DEFAULT_MAX_LINES}} lines starting from the beginning of the file
-- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
-- Any lines longer than 500 characters will be truncated
-- By default, results omit line numbers. Use `lines: true` to include them
-- This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.
-- This tool can read PDF files (.pdf). PDFs are processed page by page, extracting both text and visual content for analysis.
-- This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs, combining code, text, and visualizations.
-- This tool can only read files, not directories. To read a directory, use the ls tool.
-- You can call multiple tools in a single response. It is always better to speculatively read multiple potentially useful files in parallel.
-- You will regularly be asked to read screenshots. If the user provides a path to a screenshot, ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths.
-- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
-
-Empty files trigger a warning. Directory paths return an ls-style listing. Missing files return an error with closest matches (gitignore respected).
-
-## Best Practices
+Reads files from the local filesystem or internal URLs.
 
+<instruction>
+- Reads up to {{DEFAULT_MAX_LINES}} lines by default
+- Use `offset` and `limit` for large files
+- Use `lines: true` to include line numbers
+- Supports images (PNG, JPG) and PDFs
+- For directories, use the ls tool instead
 - Parallelize reads when exploring related files
-- Read before editing (required in current session)
-- Trust user-provided paths; attempt the read
-- Screenshots: Read tool renders images visually
-- Skip re-reading after edits (Edit/Write report errors)
+- Supports internal URLs:
+  - `skill://<name>` - read SKILL.md for a skill
+  - `skill://<name>/<path>` - read relative path within skill directory
+  - `rule://<name>` - read rule content
+  - `agent://<id>` - read agent output artifact
+  - `agent://<id>/<path>` or `agent://<id>?q=<query>` - extract JSON from agent output
+</instruction>
+
+<output>
+- Returns file content as text
+- Images: returns visual content for analysis
+- PDFs: returns extracted text
+- Missing files: returns closest filename matches for correction
+- Internal URLs: returns resolved content with pagination support
+</output>

package/src/prompts/tools/replace.md

@@ -1,18 +1,24 @@
+# Replace
+
 Performs string replacements in files with fuzzy whitespace matching.
 
-Usage:
-- Use the smallest edit that uniquely identifies the change. To toggle a checkbox: `- [ ] Task` → `- [x] Task`, not the entire line.
-- If the old text is not unique, expand the replacement to a larger block (function/class/section) so it is unique.
-- You must use your read tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
-- Fuzzy matching handles minor whitespace/indentation differences automatically - you don't need to match indentation exactly.
-- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
-- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
-- The edit will FAIL if old_string is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance of old_string.
-- Use replace_all for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.
+<instruction>
+- Use the smallest edit that uniquely identifies the change
+- If `old_text` is not unique, expand to include more context or use `all: true` to replace all occurrences
+- Fuzzy matching handles minor whitespace/indentation differences automatically
+- Prefer editing existing files over creating new ones
+</instruction>
+
+<output>
+Returns success/failure status. On success, the file is modified in place with the replacement applied. On failure (e.g., `old_text` not found or matches multiple locations without `all: true`), returns an error describing the issue.
+</output>
 
-## When to use bash instead
+<critical>
+- You must read the file at least once in the conversation before editing. The tool will error if you attempt an edit without reading the file first.
+</critical>
 
-Edit is for content-addressed changes—you identify *what* to change by its text.
+<bash_alternatives>
+Replace is for content-addressed changes—you identify *what* to change by its text.
 
 For position-addressed or pattern-addressed changes, bash is more efficient:
 
@@ -27,5 +33,6 @@ For position-addressed or pattern-addressed changes, bash is more efficient:
 | Copy lines N-M to another file | `sed -n 'N,Mp' src >> dest` |
 | Move lines N-M to another file | `sed -n 'N,Mp' src >> dest && sed -i 'N,Md' src` |
 
-Use Edit when the *content itself* identifies the location.
+Use Replace when the *content itself* identifies the location.
 Use bash when *position* or *pattern* identifies what to change.
+</bash_alternatives>

package/src/prompts/tools/ssh.md

@@ -1,11 +1,14 @@
-Execute commands on remote SSH hosts.
-
-## Critical: Match Commands to Host Shell
+# SSH
 
-Each host runs a specific shell. **You MUST use commands native to that shell.**
+Execute commands on remote SSH hosts.
 
-### Command Reference
+<instruction>
+1. Check the host's shell type from "Available hosts" below
+2. Use ONLY commands for that shell type
+3. Construct your command using the reference below
+</instruction>
 
+<commands>
 **linux/bash, linux/zsh, macos/bash, macos/zsh** — Unix-like systems:
 - Files: `ls`, `cat`, `head`, `tail`, `grep`, `find`
 - System: `ps`, `top`, `df`, `uname`, `free` (Linux), `df`, `uname`, `top` (macOS)
@@ -26,49 +29,39 @@ Each host runs a specific shell. **You MUST use commands native to that shell.**
 - Files: `dir`, `type`, `findstr`, `where`
 - System: `tasklist`, `systeminfo`
 - Navigation: `cd`, `echo %CD%`
+</commands>
 
-## Execution Pattern
+<output>
+Command output (stdout/stderr combined), truncated at 50KB. Exit code is captured.
+If output is truncated, full output is stored under $ARTIFACTS and referenced as `artifact://<id>` in metadata.
+</output>
 
-1. Check the host's shell type from "Available hosts" below
-2. Use ONLY commands for that shell type
-3. Construct your command using the reference above
+<critical>
+Each host runs a specific shell. You MUST use commands native to that shell.
+Verify host shell type from "Available hosts" and use matching commands.
+</critical>
 
-## Examples
-
-<example>
+<example name="linux">
 Task: List files in /home/user on host "server1"
 Host: server1 (10.0.0.1) | linux/bash
 Command: `ls -la /home/user`
 </example>
 
-<example>
+<example name="windows-cmd">
 Task: Show running processes on host "winbox"
 Host: winbox (192.168.1.5) | windows/cmd
 Command: `tasklist /v`
 </example>
 
-<example>
+<example name="windows-wsl">
 Task: Check disk usage on host "wsl-dev"
 Host: wsl-dev (192.168.1.10) | windows/bash
 Command: `df -h`
 Note: Windows host with WSL — use Unix commands
 </example>
 
-<example>
+<example name="macos">
 Task: Get system info on host "macbook"
 Host: macbook (10.0.0.20) | macos/zsh
 Command: `uname -a && sw_vers`
 </example>
-
-## Parameters
-
-- **host**: Host name from "Available hosts" below
-- **command**: Command to execute (see Command Reference above)
-- **cwd**: Working directory (optional)
-- **timeout**: Timeout in seconds (optional)
-
-## Output
-
-Truncated at 50KB. Exit codes captured.
-
-**Before executing: verify host shell type below and use matching commands.**