use-aio

Informational, not binding. Know a better way for the case in front of you — do it your way and say so. You are trusted with the creative work on this project.

AIO is SEO with a different reader. The engine sends a person; the model arrives itself, reads and retells. So the page must exist twice: as a page, and as its text.

🔒 A model is not promised to run JavaScript. OpenAI's own bot documentation says nothing about executing it — so the finished CONTENT has to be in the server markup, not assembled after hydration. Motion, tabs and reveals belong on top of a printed twin, never instead of it (use-widgets). A section that only exists after hydration exists for nobody here.

1. One registry feeds all three surfaces

lib/aio/surfaces.ts is the single list of public surfaces. From it come llms.txt (the map), llms-full.txt (all texts in one document) and every page's markdown twin. One list means a new page appears in all three at once or in none — a map that disagrees with the site is physically impossible.

Posts and products need no entry: posts come from _list.generated.ts inside the registry, and product cards carry their own twin at their own address. A new SECTION or standalone page is the case that needs your hands — a registry line and an index.md/route.ts next to the page.

2. The address of a twin always carries the language

mdUrlFor(lang, subPath) → <origin>/<lang><subPath>/index.md, even in single-language mode, where the page itself has no language segment. Not a matter of taste: proxy.ts deliberately ignores any path containing a dot (the same exclusion that lets /llms.txt through), so nobody is left to rewrite /index.md into /en/index.md — and the route physically lives under app/[lang]/. It shipped wrong once and the first link of the map answered 404.

The twin is also announced from the page: buildAlternates puts it in alternates.types as text/markdown. A model that follows it skips the menu, the footer, the consent banner and the scripts — which is the entire saving.

3. The route is three declarations and a shared brain

const md = markdownRoute("/blog")
export const dynamic = "force-static"
export const dynamicParams = false
export const generateStaticParams = md.generateStaticParams
export const GET = md.GET

Segment values are declared literally: Next parses them statically and refuses a re-export from an object ("needs to be a static boolean").

4. 🔒 One source of text, never a hand-written file "for the AI"

The twin is built from the SAME blocks as the page. A separate hand-written copy diverges at the first edit and nobody notices, because nobody opens a markdown twin in a browser — today that divergence is a model quoting a price you changed last month.

5. What goes in the map, and what never does

What the format is FOR, in the words of its own specification: inference, not training. A model reading the site to answer a question now — not a corpus somebody trains on. Say that when asked, and do not stretch it: the specification makes no promise either way about training.

llms.txt follows llmstxt.org literally: # Title, a > quote carrying everything needed to understand the rest, optional prose without headings, then ## Section lists of - [name](url): note. The section named ## Optional is from the specification — it marks links an agent may skip when trimming context, so its name is not translated; legal pages go there.

• Sections are named, rows are not. The map names the catalogue; individual products are reached through the sitemap and their own twins. A file that grows to its limit stops working whole — the same lesson as sitemap.xml and its 50 000 URLs.
• Nothing behind a role, ever. A page under (protectedLayer) has no twin and no map entry. The map is an invitation to read; a closed address in it invites an agent to knock where it was not called. check:aio enforces both halves.
• llms-full.txt is community practice, not a standard. It does not exist in the specification, the file says so in its own first line, and check:aio fails if the word "standard" appears next to it. Calling practice a standard is how a wrong fact enters documentation, marketing and support answers at once.

6. What the gate refuses

npm run check:aio, and it runs inside prebuild — a build with a public page missing its twin does not complete, so it never deploys:

• a public page with no neighbouring index.md;
• a markdown twin under a role-gated route;
• a map that is still a stub instead of being built from the registry;
• llms-full.txt described as a standard.

7. Before you call it done

Two proofs from different planes, and the gate is only one of them:

• fetch /<lang>/<page>/index.md and read the text — headings, body, FAQ, all of it present;
• fetch /llms.txt and /<lang>/llms.txt, find your page, and request every link you added — 200, not 404, on the real deployment;
• view the page source and confirm the content is in the server markup rather than arriving with the scripts.

Green gate plus 200 on the page is one plane. The text of the twin is the other.