# Tool Usage Notes

Tool signatures are provided automatically via function calling.
This file documents non-obvious constraints and usage patterns.

## exec — Safety Limits

- Commands have a configurable timeout (default 60s)
- Dangerous commands are blocked (rm -rf, format, dd, shutdown, etc.)
- Output is truncated at 10,000 characters
- `restrictToWorkspace` config can limit file access to the workspace

## grep — Content Search

- Use `grep` to search file contents inside the workspace
- Default behavior returns only matching file paths (`output_mode="files_with_matches"`)
- Supports optional `glob` filtering (e.g. `glob="*.py"`) plus `context_before` / `context_after`
- Supports `type="py"`, `type="ts"`, `type="md"` and similar shorthand filters
- Use `fixed_strings=true` for literal keywords containing regex characters
- Use `output_mode="files_with_matches"` to get only matching file paths
- Use `output_mode="count"` to size a search before reading full matches
- Use `head_limit` and `offset` to page across results
- Prefer this over `exec` for code and history searches
- Binary or oversized files may be skipped to keep results readable

## cron — Background Agent Tasks

- Use `cron` only for **background agent tasks** (scripts, checks, autonomous actions).
- For **personal reminders to the user**, use the `/remind` skill instead (stored in SQLite `db/reminders.sqlite`).
- Do not call `nanobot cron` via `exec` — use the built-in `cron` tool.

## python — use uv

For all Python code (scripts, snippets, one-liners, tools) use `uv`,
not `python` / `python3` / `pip` directly.

- Run a script: `uv run script.py` (not `python script.py`)
- One-liner / snippet: `uv run --with <pkg> python -c '...'`
- Script with declared dependencies: `uv run --script script.py`
  (PEP 723 header inside the file)
- Add a project dependency: `uv add <pkg>` (not `pip install`)
- Remove: `uv remove <pkg>`
- Sync environment: `uv sync`
- Run a tool: `uv run pytest`, `uv run ruff`, `uv run mypy`, …
- REPL: `uv run python`

Do not use `pip`, `pip-tools`, `poetry`, `conda`, or the system `python`.
Reason: isolated, reproducible environments with no system-level side
effects, faster resolves, no "works on my machine" surprises.

## Doručené připomínky — „co dnes přišlo?"

Připomínky doručuje **systémový cron uživatele nanobot**
(`skills/remind/scripts/remind_send.py`) přímo přes Telegram, mimo agenta —
agent u odeslání není. Když se uživatel ptá na minulé/dnešní připomínky
(„připomněl jsi mi…?", „co dnes přišlo?"), zavolej
`uv run skills/remind/scripts/remind_edit.py delivered [--since YYYY-MM-DD]` —
čte tabulku `reminder_fires` (jen doručené, čas v Praze).

`log/reminder.log` je provozní/debug log všech operací (ADD/EDIT/REMOVE/…/DELIVER,
UTC) — ne zdroj pravdy pro doručení. `log/reminder_cron.log` zachytává
stdout/stderr crontabu — za zdravého běhu prázdný, plní se jen při pádech skriptu.