> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jacobpevans.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent context: llms.txt, registry, and RAG

> How a local-LLM agent loads project context without a human in the loop — the llms.txt exports for whole-site reading, a machine-readable model and endpoint registry, and a retrieval index over the docs for targeted questions.

> An agent has three ways to load context, in rising order of specificity: read
> the whole site as one file, resolve a model or endpoint from a registry, or
> ask a retrieval index a single question. They compose — the same docs feed all
> three.

Docs written for humans are also the raw material an agent runs on. Three small,
boring conventions make that work without bespoke scraping, and none of them
needs a human in the loop.

## llms.txt — read the whole thing

This site emits the [llmstxt.org](https://llmstxt.org) files at build time:

* `/llms.txt` — a curated link index of the site.
* `/llms-full.txt` — every page concatenated into one document.

An agent fetches `llms-full.txt` when it wants the entire corpus in context, and
`llms.txt` when it wants to pick pages to fetch. Both are plain text at stable
URLs, so consuming them is a single HTTP GET — no crawler, no sitemap parsing.

## The registry — resolve a model or an endpoint

Hard-coding a model id or an endpoint into an agent is how it breaks the next
time either changes. The pattern instead is a small machine-readable registry —
a flat JSON object keyed by **capability role** rather than physical name:

* `models`: role → model id (`default`, `quickest`, `tool-calling`, `coding`,
  `large-context`, …). The role is the stable contract; the model behind it can
  change without touching the agent.
* `endpoints`: name → OpenAI-compatible base URL.
* `nodeports` / versions: well-known ports and pinned tool versions.

In this project that file is generated by [`nix-ai`](/nix/nix-ai) on every
rebuild and lands at a stable path the agent reads. An agent resolves
`models["tool-calling"]` and `endpoints[...]` at startup instead of embedding
literals — see [backends and tool calling](/local-llm/backends) for why the
tool-calling role is the one that actually matters.

## RAG — ask one question

For a targeted question, whole-site context is wasteful. The retrieval pattern
embeds the docs into a vector store and answers by similarity:

1. Ingest `llms-full.txt` (already the whole corpus in one file) as the source.
2. Embed each chunk with an OpenAI-compatible embeddings endpoint — the same
   endpoint the registry already names, so there is no second embedding path to
   keep in sync.
3. Store vectors in a vector database (Qdrant is a common choice) and query by
   similarity at agent time.

Because the ingestion source is the same `llms-full.txt`, the retrieval index
stays in step with the docs by rebuilding whenever the site does.

## How they fit

| Need                       | Use             | Cost                         |
| -------------------------- | --------------- | ---------------------------- |
| Full corpus in context     | `llms-full.txt` | One GET; largest token load  |
| Resolve a model/endpoint   | registry JSON   | One read; tiny               |
| Answer a specific question | RAG query       | One similarity search; small |

Start with the registry to wire up the model and endpoint, reach for
`llms-full.txt` when the whole corpus is worth the tokens, and stand up RAG when
questions are frequent and specific enough that re-reading everything is waste.
See [the local-LLM overview](/local-llm/overview) for how the serving side of
this fits together.