# vera-search-tools

## Purpose
Provide fast local workspace search for Pi via bundled `rg` and `fd`, plus integrity and runtime diagnostics.

Search results are progressively paged: `rg` and `fd` return 5 results by default and expose `offset` / `limit` so the agent can continue searching in small slices instead of dumping everything at once. Output footers now include `next_offset` / `use_offset` to make continuation explicit.

## Non-goals
- web search, page reading, docs lookup, or PDF parsing
- session UI, banners, or thinking shortcuts
- compaction, prompt assembly, or provider compatibility patches
- silently replacing built-in `grep` / `find` contracts that Pi may rely on

## Registered surface

### Tools
- `rg`
- `fd`

### Commands
- `/search-tools` — show bundled rg/fd status, source (embedded vs system), and sha256 integrity
- `/search-tools ensure` — download and verify bundled rg/fd for the current platform

### Hooks
- `session_start` — verifies search binary availability, auto-fetches missing or corrupted binaries once, and warns only if repair fails

## Config / auth
This package does not require API keys.

It relies on:
- bundled binaries under `bin/`
- integrity metadata in `manifest.json`
- optional system `rg` / `fd` fallback when bundled binaries are unavailable

## External dependencies
- network access only when `session_start` auto-repair or `/search-tools ensure` fetches binaries
- executable support for the current platform

## Smoke
- `npm run smoke`
- from project root: `node scripts/smoke-all.mjs`

## Debugging
1. Run `/search-tools` to see bundled-vs-system source, sha256 integrity, and system grep/find fallback.
2. If binaries are missing or corrupted, run `/search-tools ensure` to re-download.
3. For package-only verification, run `node packages/vera-search-tools/scripts/smoke.mjs`.

Loaded through `agent/settings.json` as `./packages/vera-search-tools`.