Reading these docs as an agent

How LLMs and coding agents fetch SEON documentation as Markdown — the URL conventions, the llms.txt indexes, and what the site does differently at the serving layer.

Most readers of this site are people. An increasing share are not: coding agents and LLMs read documentation on a developer's behalf before that developer writes a line of integration code. If what they read is stale, incomplete or expensive to parse, the integration comes out wrong — and the developer experiences that as SEON is hard to integrate.

This page is the contract for those readers. Everything below is a build output of this repository, regenerated on every merge.

Getting a page as Markdown

Every page is published at three URLs: one for people, two for agents.

Two Markdown conventions exist because agents guess differently. Appending /index.md to a URL is the more widely adopted convention; the sibling .md is what a static site naturally produces. Both serve identical bytes, so it does not matter which one an agent tries first.

The Markdown is the source file with its front matter stripped — no navigation, no scripts, no styling, no hydration payload. Just the page.

Content negotiation

The canonical URL also answers to an Accept header, so an agent that already holds a link does not need to know our path conventions:

curl https://docs.seon.dev/integration/orchestration \
  -H "Accept: text/markdown"

Any response that varies on the request header must say so, or a shared cache will serve Markdown to a browser and HTML to an agent:

# Serve the Markdown twin when the client asks for it.
location ~ ^/(?<page>.+?)/?$ {
    if ($http_accept ~* "text/markdown") {
        rewrite ^ /$page.md last;
    }
    try_files /$page.html /$page/index.html =404;
}

location ~ \.md$ {
    add_header Content-Type "text/markdown; charset=utf-8";
    add_header Vary "Accept";
}

Discovery: llms.txt

Agents need to find pages before they can read them. The build emits three indexes, following the llmstxt.org convention.

The root index looks like this:

# SEON Docs

> Documentation for SEON's fraud prevention, AML and identity verification
> platform — API reference, SDK integration guides and knowledge base.

## Integration

- [Orchestration](/integration/orchestration.md): Running IDV, liveness and
  proof of address inside a configurable workflow.

Pages we do not want agents to read

Not every live page is a page we still recommend. Legacy integration paths stay published because existing customers have them bookmarked, but an agent that learns from them will confidently recommend the wrong approach to somebody starting today.

Marking a page deprecated in its front matter removes it from every agent surface:

---
title: Legacy IDV session endpoints
status: deprecated
---

A deprecated page still renders, and its Markdown twin is still written so direct links resolve. But it is excluded from llms.txt, excluded from llms-full.txt, and disallowed in robots.txt.

What this costs, measured

The Orchestration integration page, fetched three ways and tokenised with cl100k_base:

The middle row is worth noticing. Even a clean, purpose-built HTML page costs roughly six times what the Markdown costs, because HTML is markup-dense and tokenises badly. Serving Markdown is not a marginal optimisation over serving better HTML — it is a different order of magnitude.

On the live site the gap is wider still: roughly half of a knowledge-base page is a JSON hydration payload duplicating content the agent already received.

Summary for implementers

Adding the agent surface to a Markdown-native docs site is four things, and only one of them is content:

1. Build — emit <path>.md and <path>/index.md beside every HTML page
2. Build — emit /llms.txt, /<section>/llms.txt and /llms-full.txt
3. Serve — content negotiation on Accept: text/markdown, with Vary: Accept
4. Content — front matter that marks deprecated pages, plus this page

Items 1, 2 and 4 live in this repository. Item 3 lives in the web server config, and is the only part that cannot ship as Markdown.