# tool-query

`tool-query` is a Bun CLI for Linux x64 that catalogs invokable commands from `PATH`, blocks search until every visible command has one-sentence metadata, and then performs semantic capability search with a first-run-downloaded Vulkan `llama.cpp` runtime plus EmbeddingGemma GGUF.

## Runtime Requirements

- Bun `>= 1.3.9`
- Linux `x64`
- Vulkan-capable machine for the semantic embedding path

## Package

- npm package: `@howaboua/tool-query`
- CLI binary: `tool-query`

## Install

```bash
npm install -g @howaboua/tool-query
```

`tool-query` is a Bun-native package. The installed binary uses the `bun` shebang, so `bun` must be present on the machine.

On first semantic search, `tool-query` downloads:
- the Vulkan `llama.cpp` runtime into `${XDG_CACHE_HOME:-$HOME/.cache}/tool-query/runtime`
- the EmbeddingGemma GGUF model into `${XDG_CACHE_HOME:-$HOME/.cache}/tool-query/models`

## Repo Map

- `src/main.ts`: entrypoint, exit codes, and stdout JSON envelope.
- `src/cli.ts`: positional command parsing and JSON payload validation.
- `src/app.ts`: high-level command orchestration.
- `src/command_index.ts`: Linux `PATH` scan and first-match command resolution.
- `src/search/`: sync-and-gate search flow plus lexical ranking.
- `src/store/`: SQLite schema, sync, metadata persistence, and validation.
- `src/embedder/`: config, runtime download, model download, and fingerprint lifecycle.
- `src/xdg.ts`: cache/config path resolution.

## Workflow

1. `tool-query search '{"query":"browser automation"}'` syncs the current `PATH`.
2. If any visible command lacks metadata, search returns `metadata_required`.
3. `tool-query describe '{"entries":[{"name":"agent-browser","description":"CLI for browser automation, page interaction, and screenshots."}]}'` writes up to five one-sentence descriptions.
4. Once every visible command is documented, `tool-query search ...` returns matching command names.

## Local Checks

Run `./scripts/check`.
