# WTF-P bundled tools

<!-- Generated by WTF-P adapter compiler v5 from protocol/tools.json; do not edit. -->

Only implementations declared by `tools.json`, the dispatcher, and its private CiteNexus companion dependency are packaged here. Resolve each logical implementation URI through this exact mapping; do not search for or execute undeclared installer/compiler modules.

- `wtfp://tools/bibliography/analyze-impact` → `tools/bibliography/analyze-impact.js` (legacy module `analyze-impact.js`)
- `wtfp://tools/bibliography/format` → `tools/bibliography/format.js` (legacy module `bib-format.js`)
- `wtfp://tools/bibliography/index` → `tools/bibliography/index.js` (legacy module `bib-index.js`)
- `wtfp://tools/citation/fetch` → `tools/citation/fetch.js` (legacy module `citation-fetcher.js`)
- `wtfp://tools/citation/rank` → `tools/citation/rank.js` (legacy module `citation-ranker.js`)
- `wtfp://tools/citation/scholar-lookup` → `tools/citation/scholar-lookup.js` (legacy module `scholar-lookup.js`)
- `wtfp://tools/citation/semantic-scholar` → `tools/citation/semantic-scholar.js` (legacy module `semantic-scholar.js`)
- Private dependency: `tools/support/cite-nexus-client.js`; reached only through `citation.fetch`, never executed directly.

## Executing a bundled tool

A `tool.execute` effect authorises exactly one command, run from the package root that the host resolves for this bundle:

```bash
node <package-root>/tools/wtfp-tool.js [--offline] <command> [arguments]
```

Run it with no argument, or with `list`, to print the declared command set as JSON; each entry carries the `effects` the command may apply. `<command> --help` prints that one entry and exits 0. Declared commands:

- `bib-index <bib-file> [--key=<citation-key>] [--query=<text>]` → `bibliography.index` (filesystem.read)
- `bib-format <bib-file> --key=<citation-key> [--style=<bibtex|al-folio>]` → `bibliography.format` (filesystem.read)
- `bib-impact <bib-file> [--timeout=<seconds>]` → `bibliography.analyze-impact` (filesystem.read, network.search)
- `citation-search --query=<text> [--backend=<legacy|cite-nexus>] [--providers=<comma-separated-IDs>] [--limit=<1-25>] [--intent=<seminal|recent|balanced>] [--year=<yyyy>] [--timeout=<seconds>]` → `citation.fetch` (network.search)
- `scholar-search --query=<text> [--limit=<1-25>] [--timeout=<seconds>]` → `citation.scholar-lookup` (network.search)
- `s2-search --query=<text> [--limit=<1-25>] [--year=<yyyy>] [--timeout=<seconds>]` → `citation.semantic-scholar` (network.fetch, network.search)
- `rank <papers.json> [--intent=<seminal|recent|balanced>]` → `citation.rank` (no declared effects)

For declared scholarly discovery, `citation-search --backend=cite-nexus --query="<topic>"` uses the separately installed `cite-nexus-wtfp` companion and its real MCP stdio server. Defaults are Crossref, DataCite and Europe PMC. Select providers explicitly with `--providers`. The `research-gap` full-auto route may use only free no-key public indexes (`crossref`, `datacite`, `europe_pmc`, `arxiv`) without another per-query gate; other routes require action approval naming providers and query scope. CiteNexus supports only balanced provider ordering, so omit `--intent` or use `--intent=balanced`. Results remain candidates: retain `citeNexus.sources`, field attribution, metrics, warnings and `metadata.errors`; do not infer verification or combine citation counts. The result limit is a displayed total; `metadata.total` counts the fetched deduplicated page, not the full corpus. Unavailable enrichment fails explicitly without falling back to another vendor. `WTFP_CITE_NEXUS_COMMAND` may name an absolute installed companion executable; it is operator configuration, never source content. No package is installed, server registered, or user profile changed by a tool call. Offline mode refuses this backend before process launch. Host capability blockers still apply.

Every command prints one JSON document on stdout and reports failures as `{"error": "..."}` on stderr with exit status 1. Queries are capped at 512 characters, file paths at 4096, and result limits at 25. A symlinked file is accepted and read through its resolved target, which must be a regular file. Commands whose effects include `network.*` perform outbound requests to the declared scholarly indexes; pass `--offline` or set `WTFP_TOOL_OFFLINE=1` to refuse them, which is the mechanical form of "do not invoke a network-capable bibliography tool through a filesystem-only permission path". Each network command has a hard wall clock, `--timeout=<seconds>` (default 20, maximum 600); on expiry it reports `{"error": "<command> timed out after N s"}` on stderr and exits 124. `bib-impact` reports batch progress on stderr. `bib-index` flags repeated keys with `duplicate: true` and lists them under `duplicates`; `--key` refuses an ambiguous key. `bib-format` emits a standard BibTeX entry (`@article`, `@inproceedings`, ...) by default; `--style=al-folio` selects the Jekyll al-folio projection, which is not valid BibTeX. Do not execute any other module in this package directly, and do not pass a logical `project://` or `wtfp://` URI as a shell argument.