v1.0

workspace/TOOLS.md

@@ -0,0 +1,157 @@
+# TOOLS.md — Available Tools & Usage Guide
+
+## Environment
+
+- **Platform:** Windows 11
+- **Workspace:** D:\smallclaw\workspace
+- **Model:** Ollama (local)
+- **Gateway:** http://127.0.0.1:18789
+
+---
+
+## File & Shell Tools
+
+| Tool | What it does |
+|------|-------------|
+| `shell` | Execute shell/cmd commands |
+| `read` | Read file contents with line numbers |
+| `write` | Write (create/overwrite) a file |
+| `edit` | Edit specific lines in a file |
+| `list` | List directory contents |
+| `delete` | Delete a file or directory |
+| `rename` | Rename/move a file |
+| `copy` | Copy a file |
+| `mkdir` | Create a directory |
+| `stat` | Get file metadata (size, dates) |
+| `append` | Append content to a file |
+| `apply_patch` | Apply a unified diff patch |
+
+## Web Tools
+
+| Tool | What it does |
+|------|-------------|
+| `web_search` | Search the web (Google/Brave/Tavily) |
+| `web_fetch` | Fetch and parse a URL (no browser needed) |
+
+## Memory Tools
+
+| Tool | What it does |
+|------|-------------|
+| `memory_write` | Write/upsert a fact to long-term memory store |
+| `memory_search` | Keyword search USER.md + SOUL.md snippets |
+| `memory_read` | Read full contents of USER.md, SOUL.md, or IDENTITY.md |
+| `persona_read` | Read a persona file with line numbers (before editing) |
+| `persona_update` | Surgically update SOUL.md, USER.md, IDENTITY.md, MEMORY.md |
+
+## Intraday Memory
+
+| Tool | What it does |
+|------|-------------|
+| `write_note` | Write temporary note to today's intraday notes file (auto-cleaned EOD) |
+
+## Task Tools
+
+| Tool | What it does |
+|------|-------------|
+| `task_control` | List, create, update, complete tasks |
+
+## Time
+
+| Tool | What it does |
+|------|-------------|
+| `time_now` | Get current date/time |
+
+## Browser Tools
+
+| Tool | What it does |
+|------|-------------|
+| `browser_open` | Open a URL in Playwright-controlled Chrome. Creates session, returns DOM snapshot with @ref numbers. For searches, build direct URL (e.g. `github.com/search?q=query`). |
+| `browser_snapshot` | Re-scan page and return updated interactive element @ref list. Only call when you don't have a recent snapshot — never call twice in a row. |
+| `browser_click` | Click a page element by @ref number. Returns updated snapshot. |
+| `browser_fill` | Type text into an [INPUT] element by @ref number. Auto-clicks Post button on X.com composer. |
+| `browser_press_key` | Press a keyboard key (Enter, Tab, Escape, ArrowDown, etc.) |
+| `browser_wait` | Wait for page to finish loading, then return fresh snapshot (500–8000ms) |
+| `browser_scroll` | Scroll page by viewport multiplier (0.5–4.0). Use 1.75 for X/Twitter. |
+| `browser_close` | Close the browser tab |
+| `browser_get_images` | Extract all images from current page. Returns URL, type, dimensions, alt text. Optional: download to workspace/uploads, save metadata JSON |
+
+## Desktop Tools
+
+| Tool | What it does |
+|------|-------------|
+| `desktop_screenshot` | Screenshot the desktop |
+| `desktop_find_window` | Find a window by process name |
+| `desktop_focus_window` | Focus a window by process name |
+| `desktop_click` | Click at x,y coordinates |
+| `desktop_drag` | Drag from one point to another |
+| `desktop_type` | Type text |
+| `desktop_press_key` | Press a key |
+| `desktop_wait` | Wait N ms |
+| `desktop_get_clipboard` | Read clipboard |
+| `desktop_set_clipboard` | Write to clipboard |
+
+## Skills Tools
+
+| Tool | What it does |
+|------|-------------|
+| `skill_list` | List installed skills |
+| `skill_search` | Search skills by keyword |
+| `skill_install` | Install a skill from ClawHub |
+| `skill_remove` | Remove a skill |
+| `skill_exec` | Execute a skill |
+
+## Self-Maintenance Tools
+
+| Tool | What it does |
+|------|-------------|
+| `read_source` | Read SmallClaw source code files |
+| `list_source` | List SmallClaw source files |
+| `propose_repair` | Propose a self-repair patch |
+| `self_update` | Run self-update process |
+| `spawn_agent` | Spawn a sub-agent |
+
+---
+
+## Decision Table — Which Tool to Use
+
+| What you need | Use this |
+|---|---|
+| Read a website, GitHub, Reddit, docs | `web_search` + `web_fetch` |
+| Log into a site or interact with a web form | `browser_open` + `browser_click/fill` |
+| Reddit research | `web_search` with `site:reddit.com "term"` → `web_fetch` |
+| Read or create local files | `read` / `write` / `edit` / `append` |
+| Run a command or script | `shell` |
+| Interact with a desktop app | `desktop_screenshot` + `desktop_click/type` |
+| Remember something permanently | `memory_write` (upsert + stable key) |
+| Update persona/user model | `persona_update` |
+| Search what you already know | `memory_search` |
+| Read a full persona file | `memory_read` or `persona_read` |
+| Temporary note during a task | `write_note` |
+| What time is it | `time_now` |
+
+---
+
+## Critical Rules
+
+**NEVER use `shell` to open a browser.** Use `browser_open(url)` instead.
+
+**Desktop focus:** Use short process name — `"msedge"`, `"chrome"`, `"code"` — never the full window title. Fail twice → stop and report, do not loop.
+
+**Line-based edits:** Use `edit` (replace_lines) for existing files — more reliable than find/replace for whitespace-sensitive content.
+
+**Reddit:** Always `web_search` with `site:reddit.com "keyword"` then `web_fetch` individual post URLs. Never use the browser for Reddit.
+
+---
+
+## When TOOLS.md is Injected
+
+TOOLS.md is **not** always injected (saves context tokens). It is referenced when:
+- You make 3+ consecutive tool failures
+- You explicitly ask "what tools do I have"
+- System detects tool uncertainty in reasoning
+
+Otherwise, you should know your tools without being reminded.
+
+---
+
+*Last updated: 2026-04-26*