# vera-web-tools

## Purpose
Provide network-backed information retrieval tools for Pi: web search, page extraction, documentation lookup, academic search, and document parsing.

## Non-goals
- local workspace search (`rg` / `fd`)
- owning session UI, banners, or thinking shortcuts; search/read/parse logic stays non-UI, while tool-frame chrome is currently borrowed from `vera-theme`
- compaction, prompt rules, or system prompt mutation
- provider compatibility shims

## Registered tools
- `web_search` — aggregated multi-engine web search
- `web_read` — readable page extraction
- `docs_search` — library documentation lookup via Context7
- `academic_search` — scholarly search via OpenAlex
- `document_parse` — document parsing via MinerU (remote URL or local file path); writes Markdown to a required `output_path`, optionally one file per page (`paginate`)

## Config / auth
This package reads credentials from `agent/auth.json` and matching environment variables.

Supported keys:
- `exa` / `EXA_API_KEY`
- `brave` / `BRAVE_API_KEY`
- `metaso` / `METASO_API_KEY`
- `jina` / `JINA_API_KEY`
- `tavily` / `TAVILY_API_KEY`
- `context7` / `CONTEXT7_API_KEY`
- `openalex` / `OPENALEX_API_KEY`
- `mineru` / `MINERU_API_KEY`

## External dependencies
- outbound network access
- upstream service availability and rate limits
- a valid URL for `web_read`; a URL or readable local file path for `document_parse`

## Internal structure
- `src/index.ts` — Pi extension entrypoint
- `src/tools/` — tool definitions and renderers; renderers currently use `vera-theme`'s `kylinFrameForCall` / `kylinFrameForResult` tool-frame chrome helpers from the sibling package
- `src/clients/` — upstream client wrappers; search deduplication uses `src/shared/render.ts` URL normalization
- `src/shared/` — package-local auth, error, http, render, and helper utilities
- `src/types.ts` — shared detail/result types

## Boundary notes
- The package owns network search/read/docs/academic/parse behavior, not session UI; tool-frame chrome is a cross-package borrow from `vera-theme` rather than a local UI framework.
- `src/shared/render.ts` is also part of client-side normalization: `clients/search.ts` uses `normalizeUrl` when de-duplicating provider results.

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

## Debugging
1. Run the package smoke in offline mode first to verify registration and renderer stability.
2. Re-run without `--offline` to test live upstream calls.
3. If a tool fails, separate missing-key paths from upstream/network failures before changing code.
4. For renderer regressions, inspect `document_parse` first; it has explicit regression coverage.

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