tools: add ollie:prompt blocks to all core tool scripts

Migrate usage documentation from separate tools-*.md prompt files
into the tool scripts themselves via ollie:prompt...ollie:end blocks.
BuildRuntime automatically extracts and appends these to the preamble.

Migrated: file_read, file_write, file_edit, file_glob, file_grep,
lsp_definition, lsp_references, lsp_hover, lsp_rename, lsp_symbols,
lsp_diagnostics, lsp_completion, reasoning_think, memory_remember,
memory_recall.

tools/file_edit

@@ -1,6 +1,18 @@
 #!/usr/bin/env python3
-# description: Replace text in a file; old_string not found is the guard
-# Args: <file_path> <old_string> <new_string> [replace_all=true|1|yes]
+# ollie:prompt
+# ## file_edit
+#
+# Replace text in a file. Has fuzzy matching (whitespace/indent flexible).
+#
+# **Args**: `[path, old_string, new_string]` or `[path, old_string, new_string, "replace_all=true"]`
+#
+# ```
+# call_tool: calls=[{tool: "file_edit", args: ["/abs/path", "old text", "new text"]}]
+# call_tool: calls=[{tool: "file_edit", args: ["/abs/path", "old text", "new text", "replace_all=true"]}]
+# ```
+#
+# **Constraints**: Absolute paths only. Errors if `old_string` matches multiple locations — add surrounding context to disambiguate, or use `replace_all=true`.
+# ollie:end
 
 import sys
 import os

tools/file_glob

@@ -1,7 +1,20 @@
 #!/usr/bin/env bash
 # ollie:parallel read
-# description: Find files by name/path pattern, sorted by modification time (newest first)
-# Args: <pattern> [path]
+# ollie:prompt
+# ## file_glob
+#
+# Find files by glob pattern, sorted by mtime (newest first).
+#
+# **Args**: `[pattern]` or `[pattern, search_dir]`
+#
+# - First arg: glob pattern (e.g. `"*.go"`, `"**/*.ts"`).
+# - Second arg (optional): absolute search directory. Defaults to cwd.
+#
+# ```
+# call_tool: calls=[{tool: "file_glob", args: ["*.go", "/abs/search/dir"]}]
+# call_tool: calls=[{tool: "file_glob", args: ["**/*.go"]}]
+# ```
+# ollie:end
 
 pattern="$1"
 search_path="${2:-$PWD}"

tools/file_grep

@@ -1,7 +1,26 @@
 #!/usr/bin/env python3
 # ollie:parallel read
-# description: Search file contents using ripgrep (or grep fallback). Default output: file:lineno| content (one match per line).
-# Args: <pattern> [--path=<dir>] [--mode=files_with_matches|content|count] [--glob=<pattern>] [--type=<type>] [-i] [-A <n>] [-B <n>] [-C <n>] [--multiline] [--head=<n>] [--offset=<n>]
+# ollie:prompt
+# ## file_grep
+#
+# Search file contents with ripgrep. Capped at 50 matches by default.
+#
+# **Args**: `[pattern, ...flags]`
+#
+# - First arg (required): regex search pattern (positional).
+# - Remaining args: flags only. The search path is a **flag**, not a positional arg.
+#
+# ```
+# call_tool: calls=[{tool: "file_grep", args: ["pattern", "--path=/abs/dir"]}]
+# call_tool: calls=[{tool: "file_grep", args: ["TODO", "--path=src/", "--glob=*.go", "-i"]}]
+# call_tool: calls=[{tool: "file_grep", args: ["func main", "--path=/home/user/project"]}]
+# ```
+#
+# - BAD: `args: ["pattern", "/path/to/dir"]` — path must use `--path=` flag
+# - GOOD: `args: ["pattern", "--path=/path/to/dir"]`
+#
+# **Flags**: `--path=<dir>`, `--mode=files_with_matches|content|count`, `--glob=<pattern>`, `--type=<type>`, `-i`, `-A <n>`, `-B <n>`, `-C <n>`, `--multiline`, `--head=<n>`, `--offset=<n>`.
+# ollie:end
 
 import sys
 import os

tools/file_write

@@ -1,6 +1,17 @@
 #!/usr/bin/env python3
-# description: Write or overwrite a file
-# Args: <file_path> <content>
+# ollie:prompt
+# ## file_write
+#
+# Create or overwrite a file. Produces a unified diff.
+#
+# **Args**: `[path, content]`
+#
+# ```
+# call_tool: calls=[{tool: "file_write", args: ["/abs/path", "file content here"]}]
+# ```
+#
+# **Constraints**: Absolute paths only. Parent directory must exist.
+# ollie:end
 
 import sys
 import os

tools/lsp_completion

@@ -1,7 +1,18 @@
 #!/usr/bin/env python3
 # ollie:parallel read
-# description: Get completions at cursor position from the language server.
-# Args: <file> <line> <col>
+# ollie:prompt
+# ## lsp_completion
+#
+# Completion candidates at cursor position.
+#
+# **Args**: `[path, line, col]`
+#
+# ```
+# call_tool: calls=[{tool: "lsp_completion", args: ["/abs/path.go", "42", "10"]}]
+# ```
+#
+# **Returns**: up to 20 candidates.
+# ollie:end
 
 import os
 import sys

tools/lsp_definition

@@ -1,7 +1,18 @@
 #!/usr/bin/env python3
 # ollie:parallel read
-# description: Go to definition of symbol at position. Returns file:line:col.
-# Args: <file> <line> <col>
+# ollie:prompt
+# ## lsp_definition
+#
+# Go to definition of symbol at position.
+#
+# **Args**: `[path, line, col]`
+#
+# ```
+# call_tool: calls=[{tool: "lsp_definition", args: ["/abs/path.go", "42", "10"]}]
+# ```
+#
+# **Returns**: `file:line:col` location(s).
+# ollie:end
 
 import os
 import sys

tools/lsp_diagnostics

@@ -1,7 +1,16 @@
 #!/usr/bin/env python3
 # ollie:parallel read
-# description: Get diagnostics (errors, warnings) for a file.
-# Args: <file>
+# ollie:prompt
+# ## lsp_diagnostics
+#
+# Errors and warnings for a file.
+#
+# **Args**: `[path]`
+#
+# ```
+# call_tool: calls=[{tool: "lsp_diagnostics", args: ["/abs/path.go"]}]
+# ```
+# ollie:end
 
 import os
 import sys

tools/lsp_hover

@@ -1,7 +1,16 @@
 #!/usr/bin/env python3
 # ollie:parallel read
-# description: Get type/documentation info for symbol at position.
-# Args: <file> <line> <col>
+# ollie:prompt
+# ## lsp_hover
+#
+# Type signature and documentation for symbol at position.
+#
+# **Args**: `[path, line, col]`
+#
+# ```
+# call_tool: calls=[{tool: "lsp_hover", args: ["/abs/path.go", "42", "10"]}]
+# ```
+# ollie:end
 
 import os
 import sys

tools/lsp_references

@@ -1,7 +1,20 @@
 #!/usr/bin/env python3
 # ollie:parallel read
-# description: Find all references to symbol at position. Returns file:line:col per reference.
-# Args: <file> <line> <col>
+# ollie:prompt
+# ## lsp_references
+#
+# Find all references to symbol at position. Capped at 50.
+#
+# **Args**: `[path, line, col]`
+#
+# ```
+# call_tool: calls=[{tool: "lsp_references", args: ["/abs/path.go", "42", "10"]}]
+# ```
+#
+# **Returns**: `file:line:col` per reference.
+#
+# **Prefer over `file_grep`** for semantic references — won't match comments, strings, or unrelated identifiers.
+# ollie:end
 
 import os
 import sys

tools/lsp_rename

@@ -1,6 +1,17 @@
 #!/usr/bin/env python3
-# description: Rename symbol at position across the workspace. Applies edits directly to files.
-# Args: <file> <line> <col> <new_name>
+# ollie:prompt
+# ## lsp_rename
+#
+# Rename symbol across workspace. Applies edits directly.
+#
+# **Args**: `[path, line, col, new_name]`
+#
+# ```
+# call_tool: calls=[{tool: "lsp_rename", args: ["/abs/path.go", "42", "10", "NewName"]}]
+# ```
+#
+# **Prefer over manual find-and-replace** — understands scope, interfaces, cross-package references.
+# ollie:end
 
 import os
 import sys

tools/lsp_symbols

@@ -1,7 +1,17 @@
 #!/usr/bin/env python3
 # ollie:parallel read
-# description: List symbols in a file or search workspace symbols.
-# Args: <file_or_query> [--workspace]
+# ollie:prompt
+# ## lsp_symbols
+#
+# List symbols in a file, or search workspace-wide.
+#
+# **Args**: `[path]` or `[query, "--workspace"]`
+#
+# ```
+# call_tool: calls=[{tool: "lsp_symbols", args: ["/abs/path.go"]}]
+# call_tool: calls=[{tool: "lsp_symbols", args: ["MyFunc", "--workspace"]}]
+# ```
+# ollie:end
 
 import os
 import sys

tools/memory_recall

@@ -1,8 +1,25 @@
 #!/usr/bin/env bash
 # ollie:parallel read
 # ollie:tier cold
-# description: Search memories by keyword, tag, or title
-# Args: <query>
+# ollie:prompt
+# ## memory_recall
+#
+# Search stored memories for relevant context.
+#
+# **Trigger condition**: ALWAYS recall before exploring code or starting work on a task. Memory is a first-class source of context — check it before reading files or running commands.
+#
+# **Calling convention**:
+# ```
+# call_tool: calls=[{tool: "memory_recall", args: ["<query>"]}]
+# ```
+# - `query`: single keyword or short term. Prefer single keywords over phrases.
+#
+# **Returns**: matching memory files.
+#
+# **Constraints**:
+# - Recall at the start of a topic, not mid-task.
+# - If recall returns nothing relevant, proceed without it.
+# ollie:end
 
 [ -z "$*" ] && echo "usage: memory_recall <query>" && exit 1
 

tools/memory_remember

@@ -1,6 +1,28 @@
 #!/usr/bin/env python3
-# description: Save a memory as a denote-formatted flat file
-# Args: <title> <tags_csv> <body>
+# ollie:prompt
+# ## memory_remember
+#
+# Persist a fact that would otherwise be lost when the session ends.
+#
+# **Trigger condition**: the user states a preference, constraint, or decision affecting future work; you discover a non-obvious fact about the codebase, system, or environment; a debugging session surfaces a root cause worth keeping; the user explicitly asks you to remember something. Autonomously remember architectural patterns, service relationships, API behaviors, configuration quirks, and other structural knowledge as you encounter it.
+#
+# **Calling convention**:
+# ```
+# call_tool: calls=[{tool: "memory_remember", args: ["<title>", "<tags_csv>", "<body>"]}]
+# ```
+# - `title`: short noun phrase
+# - `tags_csv`: comma-separated tags; pick specific and reusable terms
+# - `body`: the fact, written so it stands alone without session context
+#
+# **Returns**: confirmation.
+#
+# **Constraints**:
+# - One memory per distinct fact.
+# - Before writing, recall on the same topic to avoid duplicates.
+# - Do not store stale facts. If a previously stored fact is wrong, update it with `file_edit`.
+# - Never delete a memory without explicit user instruction.
+# - **Act autonomously.** Do not ask the user whether to remember something.
+# ollie:end
 
 import sys
 import os

tools/reasoning_think

@@ -1,7 +1,24 @@
 #!/usr/bin/env bash
 # ollie:parallel read
-# description: Internal reasoning scratchpad; think through complex problems before acting
-# Args: <thought>
+# ollie:prompt
+# ## reasoning_think
+#
+# Scratchpad for externalizing reasoning. Recorded in history but not shown to the user.
+#
+# **Trigger condition**: before acting on non-trivial tasks — complex problems, multi-step logic, decisions with trade-offs. Skip for simple single-step tasks.
+#
+# **Calling convention**:
+# ```
+# call_tool: calls=[{tool: "reasoning_think", args: ["your reasoning here"]}]
+# ```
+#
+# **Returns**: nothing. The value is in writing the thought.
+#
+# **Constraints**:
+# - One call per decision point.
+# - Never call reasoning_think more than once before taking an action (tool call or response). Think, then act.
+# - Keep under 200 words. State the decision and key tradeoffs, not stream-of-consciousness.
+# ollie:end
 
 [ -z "$*" ] && echo "usage: reasoning_think <thought>" && exit 1
 exit 0