AI coding agents

Your content is files in your repository, so a coding agent can already edit it. What it doesn't know is how your site's content works: which collections exist, which fields each one needs, which Markdoc tags it may use, and what to leave alone so the studio keeps working. Vesper writes that down for it.

Write your site's instructions

Run this in your site's folder:

npx vesper agents

It reads src/content.config.ts and vesper.config.ts, as the studio does, and writes a section of AGENTS.md with:

• The rules that keep the studio and your build working: change only what you mean to change, never reformat content files, write values as the file stores them, and check the result with astro build.
• What your site uses: how image fields are stored, how page trees and _order.yaml work, how to add a redirect, and every Markdoc tag and MDX component with its attributes. Each part appears only if your site has it.
• Every collection: where its files are, its URL pattern, and each field with its type, whether it's required, its default and its help text.

The section sits between two markers. Everything outside them is yours, and Vesper never changes it. Run the command again after you change your schema: it replaces its own section and nothing else.

@AGENTS.md

Keep it current

A schema change makes the instructions out of date. --check writes nothing, and fails when the file doesn't match your schema:

npx vesper agents --check

Run it in CI beside your build, and a changed schema can't leave the instructions behind. A script in package.json makes both easy to remember:

{
  "scripts": {
    "agents": "vesper agents"
  }
}

The command reference lists every option, including --root for a site inside a larger repository.

These docs, for agents

Agents read Markdown more reliably than web pages, so the docs come in both:

• /llms.txt lists every page, with a one-line summary and a link to its Markdown.
• /llms-full.txt is all of the docs in one file.
• Every page is Markdown too: put .md in place of the trailing slash, as in /docs/agents.md. The link at the bottom of each page goes there.

Give an agent the address of the page it needs, or the whole file when it's learning Vesper from scratch.

Reviewing an agent's changes

An agent's edit is an ordinary change to a file, so review it like anyone else's: the diff shows exactly what changed. When a move or rename was done by hand, check that both _order.yaml files, the redirects and the links changed with it. Moving pages in the studio does all of that for you.