# llms.txt and machine-readable docs

> **For agents:** if you have the MCP server, `search_docs(query="alert rules")`, `get_doc(slug="product/alerts")`, and `list_docs()` serve the same content without HTTP. Without MCP, fetch `https://docs.bugwatch.io/llms.txt` first.

Everything on this site is designed to be read by a model as easily as by a person. There is no JavaScript-rendered content; the HTML view is a thin layer over the same Markdown.

## Endpoints

| URL | Returns |
|---|---|
| `/llms.txt` | Index in the [llms.txt](https://llmstxt.org) format: one line per page with its `.md` URL and description, grouped by section |
| `/llms-full.txt` | Every page concatenated, each preceded by `<!-- https://docs.bugwatch.io/<slug>.md -->` |
| `/<slug>.md` | One page as raw Markdown (`text/markdown; charset=utf-8`) |
| `/<slug>` with `Accept: text/markdown` | Same as above through content negotiation; a `Link: <…/llms.txt>; rel="alternate"` header points back to the index |
| `/search?q=<terms>` | JSON: `{"query": "...", "hits": [{"slug","title","description","snippet","score"}]}` — top 5 by default |
| `/mcp-tools.json` | The MCP tool registry: name, area, description, scope, mutating flag, JSON Schema input, REST mapping, example arguments |
| `/reference/mcp-tools` | The same registry rendered as a reference page (also available as `.md`) |
| `/sitemap.xml`, `/robots.txt` | Standard crawler files; everything is crawlable |

Relative links inside a page (`/product/alerts`) are rewritten to absolute `.md` URLs in the Markdown and text views, so a fetched page never contains a link you cannot follow.

## Examples

```sh
curl -sS https://docs.bugwatch.io/llms.txt
curl -sS https://docs.bugwatch.io/quickstart.md
curl -sS -H 'Accept: text/markdown' https://docs.bugwatch.io/product/issues
curl -sS 'https://docs.bugwatch.io/search?q=source%20maps' | jq '.hits[].slug'
curl -sS https://docs.bugwatch.io/mcp-tools.json | jq '.tools[] | select(.mutating) | .name'
```

## Over MCP

The same pages are exposed as resources (`bugwatch://docs/<slug>`, `resources/list` enumerates them) and as three tools:

- `search_docs(query, limit≤20)` — ranked hits with snippets; title matches rank first.
- `get_doc(slug)` — the Markdown body.
- `list_docs()` — the table of contents.

These need only `org:read`, so every token can use them.

## Caching and freshness

Responses carry `Cache-Control: public, max-age=300`. Pages are compiled into the docs Worker at deploy time from Markdown sources in the repository; the generated tool reference is built from the same registry the MCP server executes, so a tool cannot appear in the docs without existing on the server or vice versa.