doc: rename tool-overlays to tool-definitions

README.md

@@ -62,7 +62,7 @@ Everything lives under `$XDG_CONFIG_HOME/ollie/` (default: `~/.config/ollie/`)
 | **Parallel execution** | Non-conflicting tool calls within a turn run in parallel (scope-based conflict scheduling) |
 | **Agents** | Write a JSON config in `~/.config/ollie/agents/` with agent prompt in `~/.config/ollie/prompts/` |
 | **Tools** | Drop an executable + `.meta` in `~/.config/ollie/tools/` — load at runtime via `tool_load` |
-| **Tool overlays** | Integrate external CLIs (or MCP servers via CLI bridges) with `.meta` files only — no wrapper code ([doc](doc/tool-overlays.md)) |
+| **Tool definitions** | Define tools with `.meta` files only — no wrapper script needed ([doc](doc/tool-definitions.md)) |
 | **Domain skills** | Load markdown skill modules at runtime |
 
 ## Repository layout

doc/tool-definitions.md

@@ -1,21 +1,24 @@
-# Tool Overlays
+# Tool Definitions
 
-A tool overlay is a set of `.meta` files that expose external CLIs to ollie
+A `.meta` file can define a tool without any companion executable. The `cmd`
-without wrapper scripts. The `.meta` file declares the schema and specifies
+field specifies a shell command to run — the registry executes it via shell,
-the shell command to run — no executable needed.
+passing the tool's JSON arguments on stdin.
 
-## Resolution order
+This is the same `.meta` schema used in `writing-tools.md`, but without the
+sidecar executable. No script, no binary — just the definition.
+
+## Resolution
 
 When the registry resolves a tool, it checks:
 
 1. `~/.config/ollie/tools/<name>` — local script or binary
-2. `.meta` `cmd` field — shell command string, executed directly
+2. `.meta` `cmd` field — shell command, executed directly
 3. `exec.LookPath(<name>)` — PATH lookup
 
-If a `.meta` file has a `cmd` field, the registry executes it via shell. The
+If a `.meta` file has a `cmd` field and no co-located executable exists, the
-tool's JSON arguments are passed on stdin.
+registry runs the command via shell.
 
-## Meta-only tool structure
+## Structure
 
 ```json
 {
@@ -33,7 +36,8 @@ tool's JSON arguments are passed on stdin.
 }
 ```
 
-No script, no binary — just the `.meta` file.
+The `cmd` field is the only addition to the standard `.meta` schema. All other
+fields work the same as documented in `writing-tools.md`.
 
 ## Parsing arguments
 
@@ -64,9 +68,7 @@ For subcommand-style CLIs with variable arguments:
 This extracts a `command` field, builds `--key=value` flags from remaining
 fields, and calls `my-cli <command> --key=value ...`.
 
-## Example: wrapping ripgrep
+## Example: ripgrep
-
-Expose `rg` as a tool with curated arguments:
 
 ```json
 {
@@ -87,12 +89,7 @@ Expose `rg` as a tool with curated arguments:
 }
 ```
 
-The model calls `rg_search(pattern="error", glob="*.log")`. The cmd pipeline
+## Example: kubectl
-extracts fields, builds flags conditionally, and runs `rg -g "*.log" "error" "."`.
-
-## Example: wrapping kubectl
-
-Expose common kubectl operations:
 
 ```json
 {
@@ -111,13 +108,10 @@ Expose common kubectl operations:
 }
 ```
 
-Complex routing logic lives entirely in the `cmd` field. No wrapper script.
+## Example: MCP bridge
 
-## Example: wrapping an MCP server
+MCP servers expose tools over JSON-RPC. CLI bridges like `mcp-client-cli` let
-
+you call them from the command line:
-MCP servers expose tools over JSON-RPC. CLI bridges like `mcp-client-cli` or
-`npx @anthropic/mcp-client` let you call them from the command line. Wrap the
-bridge in a `.meta`:
 
 ```json
 {
@@ -136,63 +130,21 @@ bridge in a `.meta`:
 }
 ```
 
-The `cmd` extracts the tool name, passes remaining args as JSON to the MCP
+This works for any MCP server with a CLI bridge. See `doc/resources/no-mcp.md`
-bridge. No MCP protocol implementation needed — the bridge handles it.
+for why ollie uses this pattern instead of implementing MCP natively.
 
-This pattern works for any MCP server with a CLI bridge: filesystem, database,
+## Installation
-Slack, linear, etc.
 
-## Overlay structure
+Copy the `.meta` file to `~/.config/ollie/tools/`. The tool is live immediately
-
+— no restart needed.
-An overlay is a directory (usually a git repo) with `.meta` files, agent
-configs, and prompts:
 
+```sh
+cp my_tool.meta ~/.config/ollie/tools/
 ```
-my-overlay/
-├── tools/
-│   ├── tool_a.meta
-│   └── tool_b.meta
-├── agents/
-│   └── my-agent.json
-├── prompts/
-│   └── agent-my-agent.md
-└── justfile
-```
-
-The justfile installs to `~/.config/ollie/`:
-
-```just
-home := env_var('HOME')
-cfg := home / ".config/ollie"
-
-default: install
-
-install: tools agents prompts
-
-tools:
-    install -m644 tools/tool_a.meta {{cfg}}/tools/tool_a.meta
-    install -m644 tools/tool_b.meta {{cfg}}/tools/tool_b.meta
-
-agents:
-    mkdir -p {{cfg}}/agents
-    install -m644 agents/my-agent.json {{cfg}}/agents/my-agent.json
-
-prompts:
-    mkdir -p {{cfg}}/prompts
-    install -m644 prompts/agent-my-agent.md {{cfg}}/prompts/agent-my-agent.md
-
-uninstall:
-    rm -f {{cfg}}/tools/tool_a.meta {{cfg}}/tools/tool_b.meta
-    rm -f {{cfg}}/agents/my-agent.json
-    rm -f {{cfg}}/prompts/agent-my-agent.md
-```
-
-Run `just install`. Tools are live immediately — no restart needed.
 
 ## Notes
 
 - `additionalProperties: true` allows pass-through arguments the schema doesn't enumerate.
 - Prefix tool names to avoid collisions (`acme_deploy`, not `deploy`).
 - Test cmd pipelines: `echo '{"pattern":"TODO"}' | bash -c 'YOUR_CMD'`
-- Agent configs can auto-load overlay tools via `autoLoad`.
+- Agent configs can auto-load tools via `autoLoad`.
-- Overlays compose: multiple overlays install to the same tools directory.