docs: describe grep_files pattern and path shapes

src/plyngent/agent/directive_checkpoint.py

@@ -22,6 +22,8 @@ use `run_argv_batch` for ordered pipelines.
 - `edit_replace`: fix match / `max_replaces`; `edit_lineno` edits only lines read via \
 `read_file(with_lineno=true)`, and line numbers reset after any file write.
 - `read_file` results start with `L{begin}-{end}` (1-based lines; offset is 0-based).
+- `grep_files`: `pattern` is a Python `re` regex (not a glob, so `*.py` fails) and \
+`path` is a literal file/dir (no glob expansion).
 - Truncated results carry a `truncate_token=...`; continue with `get_truncated`.
 - Prefer `fetch` for HTTP(S); private/LAN hosts need human policy allow (not YOLO).
 - PTY secrets only via `ask_into_pty`; denylists and confirms still apply.

src/plyngent/config/models.py

@@ -43,6 +43,10 @@ re-read with line numbers after any `edit_*` / `write_file` / copy/move/delete,
 since line numbers go stale.
 - `read_file` results start with a 1-based line range `L{begin}-{end}` (`offset` \
 is 0-based); `with_lineno` shows per-line numbers instead.
+- `grep_files` takes a Python `re` regex for `pattern`, not a filename glob \
+(`*.py` / `**/*.py` fail with `invalid regex`), and a literal file/dir `path` \
+(no glob expansion, so `src/**/*.py` fails with `path does not exist`); there is \
+no file-type filter, so narrow with `path` and filter hits yourself.
 - Truncated results (any tool) carry a `truncate_token=...`; use `get_truncated` \
 with it to keep reading (chains through truncations).
 

src/plyngent/tools/file/grep_files.py

@@ -140,8 +140,22 @@ async def grep_files(
 ) -> str:
     """Search file contents under the workspace with a regular expression.
 
-    Returns ``path:line: content`` lines (paths relative to workspace root).
-    Skips VCS/hidden dirs by default and ignores likely-binary files.
+    ``pattern`` is a **Python** ``re`` regex matched per line (``re.MULTILINE``),
+    **not** a filename glob — ``*.py`` / ``**/*.py`` are invalid regexes and fail
+    with ``error: invalid regex``. There is no file-type filter either: narrow with
+    ``path`` (a file or a directory) and filter unrelated hits yourself.
+    ``case_insensitive`` (or an inline ``(?i)``) ignores case.
+
+    ``path`` is a **literal** file or directory (default ``.`` = workspace root);
+    globs are not expanded, so ``src/**/*.py`` fails with ``error: path does not
+    exist`` — pass ``src`` instead.
+
+    Returns ``<path>:<line>: <content>`` lines (workspace-relative, absolute outside
+    the workspace), long lines clipped with ``…``, capped at ``max_matches``
+    (default 100, plus a ``...[truncated at N matches]`` marker). VCS/hidden dirs are
+    skipped unless ``skip_hidden_dirs=False``; files over 1 MB and likely-binary
+    files are ignored. Returns ``(no matches)`` when nothing matched; an invalid
+    ``pattern`` or a missing ``path`` returns an ``error: ...`` line.
     """
     if max_matches < 1:
         return "error: max_matches must be >= 1"