# Engine v2 — docs search for agents

> Lexical-first developer-docs search engine built for coding agents.
> Returns token-efficient evidence packs with citations, not link lists.
> Prototype. Index is small and grows by adding docsets.

## Tools

- search_docs: GET /api/search?q=<query>&docset=<id?>&limit=<1-20?>
  Returns an evidence pack: results with title, url, anchor, heading_path,
  snippet, relevance, source_type, last_crawled, content_hash, plus
  "answerable" and "guidance" fields. Trust "guidance" for the next action.
- fetch_doc: GET /api/fetch?url=<page-url>&max_chars=<n?>
  Returns the stored normalized markdown for an indexed page.
  Send "Accept: text/markdown" to get the raw markdown body.
- list_docsets: GET /api/docsets
- add_docset: POST /api/docsets  body: {"url": "https://docs.example.com", "name"?: string, "max_pages"?: number}
  Starts a durable ingestion workflow (llms.txt first, sitemap fallback).
- refresh_docset: POST /api/docsets/<id>/refresh
- docset_status: GET /api/docsets/<id>
- feedback: POST /api/feedback  body: {"query": string, "url"?: string, "chunk_id"?: string, "outcome": "solved"|"not_helpful"|"stale"|"wrong_version", "note"?: string}
  Report whether evidence helped. This trains source ranking over time.

## Usage notes for agents

- Search before you fetch. Results are small by design; call fetch_doc only
  for pages you intend to use.
- If "answerable" is false, the corpus likely lacks coverage: add a docset
  for the library you need, poll its status, then search again.
- Results are evidence, not truth: check "last_crawled" when version matters.
- Machine-readable tool contract: GET /api/schema