Why this site exists

SEON's public documentation is written by hand, published through a CMS, and updated whenever somebody remembers. The product it describes changes every day. The gap between the two is invisible until a customer hits it — or until an AI agent reads a stale page and integrates SEON wrong.

This site is the fix. It is also the pitch for the fix, which is the point: every claim below can be checked by looking at the page you are reading.

The problem, measured

Documentation is no longer read only by people. When a developer integrates SEON, an LLM reads our docs first and writes the integration from what it found. So "how expensive is this page to read" stopped being an academic question.

We measured four live docs.seon.io pages, tokenised with cl100k_base:

Page	As served (HTML)	As Markdown	Ratio
Custom rules & parameters	141,021	5,906	23.9×
How to build a workflow	134,220	4,507	29.8×
Workflow API	96,495	3,772	25.6×
Orchestration integration	60,281	3,461	17.4×
Total	432,017	17,646	24.5×

A single knowledge-base page costs an agent roughly 141,000 tokens. All four of those pages, as Markdown, cost 17,646 — less than one-eighth of one page today. Around half of each page is a JSON hydration payload duplicating content the agent already received in the HTML.

Those figures come from the live docs.seon.io pages before this site existed. Now that both sites are up, the same pages have been measured side by side — including the two where this site carries more content than the live one and still costs 13× and 25× less. That comparison, the capability-by-capability probe of both sites, and the gaps on both sides are on Measurements.

What we built

Two halves, and they are useless apart.

1The platform — Markdown in git, rendered with Markdoc

Every page on this site is a Markdown file in a repository. Markdoc — the framework Stripe built for docs.stripe.com and released under MIT — turns it into the page you are reading, with custom tags for callouts, steps and API reference blocks generated from OpenAPI specs.

Three things fall out of that choice for free:

Versioning. Git history is the version record, for the API reference, SDK guides and knowledge base alike.
Editing. Anyone who can write Markdown can fix a page and open a pull request. No CMS queue.
Agents. Raw Markdown at a predictable URL, llms.txt indexes, and a Copy for LLM control. See Reading these docs as an agent.

2The pipeline — documentation as a build output

When something merges to master, a pipeline works out whether it changed anything a customer can observe, drafts the documentation update, applies each repository's configuration rules for what may be published, and opens a pull request. A human approves it.

The rule that governs the whole thing: every tier outputs a pull request, never a publish. The machine proposes; a person disposes.

How this documentation is generated walks one real merge through it end to end, including a merge that correctly produces nothing.

What this changes about shipping docs

Choosing Markdown in git is not only a format decision. It hands documentation the entire workflow that code already has, and none of it has to be built.

Every change is a pull request. A branch gets a preview build, so you read the rendered page before anybody else can. Dev and production stop being a CMS feature we have to configure and become the thing git does by default.

Version history is free and complete. Who changed a page, when, why, the diff between any two points in time, and a one-command revert — across the API reference, the SDK guides and the knowledge base alike. That is also a cleaner audit trail than a CMS revision log for the pages that regulated customers treat as contractual.

Anyone with repository access can write. This used to be the strongest argument for a CMS: a non-engineer could publish, and a git repository shut them out. AI coding assistants have largely collapsed that barrier — editing a Markdown file and opening a pull request is now something anyone can do by describing the change they want.

The honest caveat is that this is still a change to how people work, and docs-as-code migrations fail on author workflow far more often than on tooling. The barrier is much lower than it was two years ago. It is not zero.

Why the filter matters more than the generator

Most merges change nothing a customer can see. A pipeline that opens a pull request on every merge gets muted inside a week, and muted pipelines do not come back.

So the component that decides whether to speak is worth more than the one that writes the prose. Not every page carries the same risk either, which is why the pipeline treats three surfaces differently:

Surface	How change is detected	Drafting	Gate
API reference	Structural diff of the generated OpenAPI spec	Template	Safe to automate
Product changelog	Same diff, plus externally tagged releases	Model prose over a structured diff	Light review
Knowledge base	Model judgment over the pull request	Model	Mandatory human review

What is real, and what is not

Being straight about the seams is what makes the rest credible.


Working now	This site. The Markdoc render, the agent surface — Markdown twins, three tiers of `llms.txt`, `robots.txt` — the API reference generated from a real OpenAPI spec, and the IDV knowledge base exported from the live docs.
The actual work	Nothing generates knowledge-base prose today. Detecting what changed and drafting it is the new part, and exactly where human review stays mandatory.
Not attempted	Cutover. This site stands in parallel to `docs.seon.io` — no redirects, no SEO migration, no DNS. That is the follow-on project this demo exists to justify.

What it would take next

Finish the corpus. The IDV knowledge base is here; the rest of docs.seon.io is not.
Wire the pipeline to a real repository and let it open its first pull request against this site.
Decide who owns docs. This changes the publishing workflow, and docs-as-code migrations fail on author workflow rather than on tooling.

Everything on this page is a Markdown file in the same repository as the rest of the site. If you disagree with a number, the source is one click away in the footer.