---
title: Build for AI tools
description: Build the site so that an AI tool can read it directly: the base path in its machine files, the generated pages left out of the whole text, the version stamped.
slug: /guides/build-for-ai-tools
order: 6
visibility: public
redirects_from: []
---

# Build for AI tools

Prompt:

> Make our docs readable by AI tools, and keep the generated reference out of the whole text.

Also works: "Stamp the docs with the version they describe." "Our docs are served under /docs, not at the root."

## What your tool does

- Passes the path the site is served under as `--base`, so that the routes in the machine files are addresses an agent can open.
- Finds the section generated from another source, such as a reference section, and passes its slug as `--full-text-exclude`. Those pages stay reachable but are left out of the [whole text](/concepts/glossary/#whole-text), which keeps it small enough for an agent to read.
- Passes the version of the product the corpus describes as `--corpus-version`, so that the manifest states it.
- Builds, and reads back the index and the manifest to confirm the routes, the `Optional` listing, and the version.
- Asks which version the corpus describes when the project does not state one.

## What you need

- The web address path your docs will be served under, for example whether they sit at your site's root or under a subfolder.
- Which version of your product these pages describe.

## Before your AI starts

This section is for your AI coding tool: what it checks and gathers before it begins. You don't need to do these steps yourself.

- A corpus that passes the check and builds ([Getting started](/getting-started/)).

## Steps

### 1. Set the base path

Pass the path the site is served under as `--base`. The build writes it in front of every route in the manifest, the index, and the whole text. The pages link relatively, so the flag changes only those machine files and, given `--origin`, the address in each page's canonical link and `og:url` tag. Without it, routes start at `/`.

```text
tzdocs build --source docs --out site --base /docs
```

### 2. Keep the generated pages out of the whole text

Pass the slug of the section to leave out as `--full-text-exclude`. Its pages are left out of the whole text and the index's section listing, and the index lists them under its `Optional` heading instead. They stay pages, and the manifest marks each one `in_full_text: false`.

The prefix is [tree-relative](/concepts/glossary/#tree-relative): `/reference`, not `/docs/reference`. It matches a page whose slug equals it or begins with it followed by `/`.

```text
tzdocs build --source docs --out site --base /docs --full-text-exclude /reference
```

### 3. Stamp the version

Pass the version of the product the corpus describes as `--corpus-version`. The build writes it as the manifest's top-level `version`, so that an agent can read which version the pages describe before it opens one.

```text
tzdocs build --source docs --out site --base /docs --full-text-exclude /reference --corpus-version 2.4.0
```

### 4. Read the machine files back

Open `llms.txt` at the tree root. Confirm that the routes begin with the base path and that the excluded pages are listed under `Optional`. Open `docs.json` and confirm its `version` and each excluded page's `in_full_text: false`. [Output](/reference/output/#machine-files) describes the four files and the order in which an agent reads them.

Beside `llms.txt`, a build given `--origin` also writes `sitemap.xml`, the list of every page's absolute address that search engines read. An agent reads the index; a crawler reads the sitemap ([Publish the site](/guides/publish-the-site/)).

## Expected result

The success line gives the page count and the number of pages left out of the whole text. It has this form: `built 40 pages into site; 12 pages excluded from the full text`.

The index lists the excluded pages under `Optional` and every other page under its section, each route beginning with the base path. The manifest has the version, and the whole text contains every page except the excluded ones.

## Refusals

[Refusals and findings](/reference/refusals/) gives the exact text.

| Message | Exit code | Cause | Remedy |
| --- | --- | --- | --- |
| `--full-text-exclude needs a tree-relative slug prefix such as /reference, not "<value>"` | 2 | The prefix is not a leading-slash path with safe segments. | Write the section's slug, without the base path. |
| `--corpus-version needs a non-blank value` | 2 | The value is empty or whitespace. | Write the version text, or leave the flag out. |
| `the excluded prefix <value> matches no page` | 1 | No page's slug equals the prefix or begins with it followed by `/`. | Correct the prefix, or leave the flag out. |

## Related

- [Output](/reference/output/#machine-files) describes the index, the manifest, the Markdown copy, and the whole text.
- [Getting started](/getting-started/) lists every flag with its default.
- [Glossary](/concepts/glossary/) defines route, base path, and tree-relative.