title: Docs for AI agents description: How AI agents and tools can fetch these docs as Markdown, llms.txt, llms-full.txt, OpenAPI and over MCP, and how to point a coding agent at them.
These docs are written to be read by AI agents as well as people. Every page is available as plain Markdown, the whole set is available as one file, the REST API is described in OpenAPI, and agents connected over MCP can search and read the docs with tools. The URLs below need no account; the MCP tools need a Diffinery token, like every MCP call.
Formats
| What | URL | Content type |
|---|---|---|
| Index of every page (the llms.txt convention) | https://diffinery.com/llms.txt | text/plain |
| Every page in one Markdown file | https://diffinery.com/llms-full.txt | text/plain |
| One page as Markdown | https://diffinery.com/docs/<page>.md, for example /docs/actions/workflow-syntax.md | text/markdown |
| The overview as Markdown | https://diffinery.com/docs/index.md | text/markdown |
| REST API as OpenAPI 3.1 | https://diffinery.com/docs/api/openapi.json | application/json |
| Search index used by the docs search box | https://diffinery.com/docs/search.json | application/json |
/docs/llms.txt and /docs/llms-full.txt redirect to the root files. These responses send Access-Control-Allow-Origin: *, so browser-based tools can fetch them too.
A .md URL for a page that doesn't exist returns 404 with a short Markdown body that points to llms.txt.
Markdown pages
Each Markdown page starts with the page title as a level-1 heading, its one-line description as a blockquote and its source URL, followed by the page body:
# Merge queue
> Merge pull requests in order, each tested on top of the base branch and the pull requests ahead of it, with merge_group workflows and required checks.
Source: https://diffinery.com/docs/collaboration/merge-queue
...Links inside Markdown pages are absolute (https://diffinery.com/docs/...), so they work outside the site. Add .md to any of them to fetch that page as Markdown too.
Content negotiation
A request for an HTML docs URL with Accept: text/markdown gets the Markdown version instead, so an agent can fetch the URL it was given:
curl -H "Accept: text/markdown" https://diffinery.com/docs/collaboration/pull-requestsHTML pages also point at their Markdown version with <link rel="alternate" type="text/markdown"> in the page head and a Link response header.
Copy page
Every page in the browser has View as Markdown and Copy page buttons. Copy page puts the page's Markdown on your clipboard, ready to paste into a chat with an AI assistant.
Which format to use
- Answering one question: fetch llms.txt, pick the page from its one-line descriptions, then fetch that page's
.mdURL. This keeps the context small. - Working on Diffinery for a while (for example, porting CI): load llms-full.txt once. It holds every page in reading order, separated by
---. - Calling the REST API: read the OpenAPI document or the REST API reference. Both are generated from the server's router, so every endpoint that exists is listed. Use the REST API guide for authentication, errors and pagination.
- Using MCP: the MCP tool reference is generated from the server's tool list and matches
tools/listexactly.
Searching and reading docs over MCP
An agent connected to the Diffinery MCP server (https://diffinery.com/mcp, with Authorization: Bearer dfy_...) has two read-only tools for the docs. They work with a token of any scope:
| Tool | Arguments | Returns |
|---|---|---|
search_docs | query | Up to 8 matching pages, each with page, title, section, the matching heading, url, markdown_url and a snippet. |
read_docs | page: a slug like actions/workflow-syntax, index, or a docs URL (a .md suffix or #anchor is ignored) | page, title and markdown: the page in the same format as its .md URL. An unknown page returns an error that lists every slug. |
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"workflow_dispatch inputs"}}}Every term in the query must appear in a page for it to match. Title matches rank highest, then section headings, then body text. See MCP for connecting a client.
Pointing a coding agent at the docs
Add a line like this to your agent's instructions (CLAUDE.md, AGENTS.md, .cursorrules or similar) in repositories hosted on Diffinery:
This repository is hosted on Diffinery (https://diffinery.com), a GitHub-compatible forge.
Docs index: https://diffinery.com/llms.txt (append .md to any docs URL for Markdown).
CI uses GitHub Actions syntax; check https://diffinery.com/docs/actions/compatibility.md
before using a GitHub-only feature. Use the diffinery CLI or the MCP server at
https://diffinery.com/mcp instead of gh.Staying current
The docs ship with the server: each deploy of Diffinery serves the docs for exactly that version, and the API, CLI and MCP references are generated from the code (the API and MCP references at runtime, the CLI reference when the server is built), so they can't fall behind it. The Markdown, llms.txt, llms-full.txt, OpenAPI and search index responses are cached for at most five minutes. CI checks on every change that each page builds, that every link and anchor resolves, and that every endpoint and tool appears in the references.