fix(filesystem): tighten PIFS grep and page-read policy

pageindex/filesystem/agent.py

@@ -59,8 +59,9 @@ operating-system shell. By default the tool is read-only: use ls, tree, find,
 grep, cat, stat, and browse when listed in the workspace
 context. grep -R is lexical evidence search; grep does not support regex
 alternation such as "a|b"; run multiple grep commands or use browse for
-relevance-ranked file discovery instead. Start broad workspace questions with
-ls or tree to understand folders. After choosing a folder, use positional
+relevance-ranked file discovery instead. Use grep <query> <file> for one
+selected file; use grep -R only with folder targets. Start broad workspace
+questions with ls or tree to understand folders. After choosing a folder, use positional
 browse syntax with a quoted query, for example:
 browse /documents "Federal Reserve". If the relevant folder is uncertain, use
 browse -R /documents "Federal Reserve" to retrieve file candidates across that
@@ -78,6 +79,9 @@ JSON, then cat <path> --page <range> for exact page text evidence. Page reads
 are limited to five pages at once, and text cat --all returns only the first
 page of text lines. If a cat limit error requires a smaller call, stop when the
 evidence is sufficient; otherwise continue with another chunk before answering.
+Do not use cat --page as the first inspection command for a selected PDF or
+PageIndex document; run cat <target> --structure for that same target first.
+Do not guess PDF page numbers from grep line numbers or text offsets.
 For questions about metadata fields, available summaries, or whether metadata
 was provided, inspect stat --schema and stat <target> before making claims.
 Do not use stat as a general content/topic discovery step. For document Q&A,
@@ -98,6 +102,7 @@ Tool policy:
 - browse returns file candidates only; Do not use browse as folder semantic recall.
 - browse candidates are not final evidence. After selecting candidates, verify the relevant facts with cat or grep before making source-backed claims.
 - grep -R performs lexical evidence search.
+- Use grep <query> <path|file_ref|document_id> for a selected single file. Use grep -R only with folder targets; do not run grep -R against one file.
 - grep does not support regex alternation such as "a|b"; run separate grep commands or use browse for relevance-ranked file discovery.
 - Do not use find | grep as an exhaustive search or as proof that no document exists; find output can be scoped or limited. Use metadata filters, browse, grep on a narrowed target, or cat on likely candidates instead.
 - A single failed grep is not enough evidence to say there is no relevant document. If grep returns no matches for a workspace-topic question, verify with browse on a relevant folder or inspect likely document structure before answering no-evidence.
@@ -109,11 +114,13 @@ Tool policy:
 - Use stat only for metadata/schema/status questions or to resolve ambiguous target identity. Do not run stat merely to understand what a document says.
 - Prefer target-first cat syntax with stable targets: cat <path> --structure, cat <path> --page 31-59.
 - cat <target> --structure returns the cached PageIndex structure JSON without text fields.
+- For PDF/PageIndex document Q&A, run cat <target> --structure before the first cat <target> --page call for that target; page reads without structure are blind page guessing.
 - cat <target> --page accepts at most 5 pages at once. If a larger range is needed, first inspect cat <target> --structure and then read a smaller page range.
 - When recovering from cat page/text limit errors, stop if the evidence is sufficient; if it is not sufficient, make another smaller call before answering.
 - cat <target> --all returns at most 100 text lines; use cat <target> --range <start>-<end> for the next page.
 - After cat <target> --structure identifies a relevant section/subsection, use cat <target> --page <start>-<end> for exact evidence.
 - Use cat <target> --page <start>-<end> when the user explicitly asks for pages/page ranges or when you need exact page text to verify evidence.
+- Do not guess cat --page ranges from grep line numbers, text offsets, or table-of-contents intuition; use cat <target> --structure to map the document first.
 - Avoid fetching a broad page span unless page-level citation or verification is required.
 - Do not call cat --page <target> <start> <end>; if you need a page span, use cat <target> --page <start>-<end>.
 - For metadata or summary-field questions, run stat --schema and stat <target> for relevant files before answering; do not infer metadata presence or absence from ls/find output alone.

pageindex/filesystem/commands.py

@@ -75,7 +75,8 @@ class PIFSCommandExecutor:
             "- find <folder>: folder path is positional; do not put paths in --where",
             "- find --where: exact/canonical metadata DSL filtering using stat --schema fields only",
             "- find <folder> -maxdepth N -type f|d: bounded folder traversal for find",
-            "- grep -R: recursive lexical/FTS search only; semantic vector prefilter is disabled",
+            "- grep <query> <file>: single-file lexical evidence search without path prefixes",
+            "- grep -R <query> <folder>: recursive lexical/FTS search only; semantic vector prefilter is disabled",
             "- cat <path|file_ref|document_id> --structure: cached PageIndex structure JSON without text fields",
             "- cat <path|file_ref|document_id> --page: cached PageIndex page reads, limited to 5 pages",
             "- cat <path|file_ref|document_id> --all: text artifact reads for txt/text files, paginated at 100 lines",
@@ -444,6 +445,11 @@ class PIFSCommandExecutor:
                     require_match=True,
                 ),
             }
+        if recursive:
+            raise PIFSCommandError(
+                "grep -R is for folder targets; use grep <query> "
+                "<path|file_ref|document_id> for a single file"
+            )
         return {
             "mode": "matches",
             "query": query,
@@ -824,9 +830,10 @@ class PIFSCommandExecutor:
                 for item in data.get("data", [])
             )
         if mode == "matches":
+            if not data.get("data", []):
+                return f"# no matches for: {data.get('query', '')}"
             return "\n".join(
-                f"{self._file_target_path(item)}:{item['line']}: "
-                f"{self._compact_text(item['text'], max_chars=220)}"
+                f"{item['line']}: {self._compact_text(item['text'], max_chars=220)}"
                 for item in data.get("data", [])
             )
         return str(data)