GEO Module — @sonordev/site-kit/llms
Generative Engine Optimization (GEO) and Answer Engine Optimization (AEO) for Sonor-powered Next.js sites. Makes businesses visible to ChatGPT, Claude, Perplexity, Google AI Overviews, and voice assistants.
Architecture
Sonor API (api.sonor.io) Signal API (signal.sonor.io)
├─ GET /api/public/llms/data ◄──────────── AI generates managed_llm_schema
├─ GET /api/public/llms/txt + llms_public_summary per page
├─ GET /seo/llms/preview (auth'd) via seo-meta-optimization pipeline
└─ GET /seo/llms/analytics (auth'd)
│
▼
site-kit (npm: @sonordev/site-kit/llms)
├─ generateLLMsTxt() ← builds markdown from Sonor data
├─ createLLMsTxtHandler() ← zero-config Next.js route handler
├─ buildAiDiscoveryHeaders() ← Link header for crawler discovery
├─ AiDiscoveryLinks (layout entry) ← static public-resource links in <head>
├─ buildAiCrawlerRules() / createRobotsTxtHandler() ← robots.txt for AI crawlers
├─ writeLLMsTxtToPublic() ← build-time static file generation
├─ createLlmsRevalidateHandler() ← on-demand ISR cache bust
├─ LLMSchema (RSC) ← JSON-LD with managed_llm_schema + isPartOf
├─ SpeakableSchema ← JSON-LD for voice assistants
└─ AEO* components ← semantic HTML for AI extraction
│
▼
Next.js Site
├─ /llms.txt ← route handler (dynamic or static)
├─ /llms-full.txt ← extended version (more pages/FAQ)
├─ HTML links ← rel="describedby" for public AI resources
├─ robots.txt ← allows AI crawlers to access /llms.txt
└─ JSON-LD in <head> ← managed_llm_schema per page
Contract
The GEO system uses a shared contract (@sonordev/site-kit/llms/contract) consumed by site-kit, Sonor API, and Signal API. The contract defines:
LLM_GEO_CONTRACT_VERSION(currently1) — increment on breaking payload changesLLMS_PUBLIC_SUMMARY_MAX_LENGTH(400) — max chars for page link notes- Sanitizers —
sanitizeLlmsPublicSummary(),sanitizeLlmsDisclaimerLine(),sanitizePrimaryLanguageTag(),pickManagedLlmSchemaForJsonLd() - Page notes, titles and order —
pickLlmsPageDescription(),llmsPageListNote(),llmsPageTitle(),isLlmsListablePage(),selectLlmsPages(),groupLlmsPages(),cleanScrapedPageText(),stripContactDetails(). The Sonor API and site-kit's local generator both build page lines through these, so a page reads the same wherever the file is built (see What a page line says).
See LLM_GEO_CONTRACT.md for the full spec.
Implementation Guide
Step 1: Route Handlers (required)
// app/llms.txt/route.ts
import { createLLMsTxtHandler } from '@sonordev/site-kit/llms'
export const GET = createLLMsTxtHandler()
// Next 15+: GET handlers are dynamic by default — opt into prerendering
export const revalidate = 3600// app/llms-full.txt/route.ts
import { createLLMsFullTxtHandler } from '@sonordev/site-kit/llms'
export const GET = createLLMsFullTxtHandler()
export const revalidate = 3600Both handlers:
- Serve static
public/llms.txtif it exists (build-time optimized,preferStatic: truedefault) - Fall back to dynamic generation from Sonor API
- Set
Cache-Controlwiths-maxage=3600andstale-while-revalidate=86400 - Return a weak
ETag(conditionalIf-None-Match/304 handling happens at the Next static layer / CDN) - Include
X-Generated-AtandX-Sectionsresponse headers - Never read the incoming
Request, so the route prerenders statically (○) instead of bailing out with a "Dynamic server usage" error duringnext build
Step 2: Discovery links (required)
HTML discovery (recommended)
// app/layout.tsx
import { SiteKitLayout } from '@sonordev/site-kit/layout'
<SiteKitLayout llmsDiscovery={{ siteUrl: 'https://example.com', mcpServerCard: true }}>
{children}
</SiteKitLayout>This renders public-resource links in the HTML head without changing Next's
resource preload headers. You can also render AiDiscoveryLinks from the same
entry in a public layout. See layout discovery
for options and private-route semantics.
HTTP compatibility
buildAiDiscoveryHeaders remains available where you control the final response
and can merge all Link values. Proxy llmsDiscovery and next.config
llmsTxtDiscoveryLink still work, but are deprecated: some host adapters replace
Next's font/style preload headers when either option sets Link. Remove that
configuration when moving to HTML discovery; changing set to append in the
proxy doesn't merge headers generated downstream.
Both renderers use the same options, including multilingual alternates:
<AiDiscoveryLinks
siteUrl="https://example.com"
languageAlternates={[{ hreflang: 'fr', href: 'https://example.com/fr/llms.txt' }]}
/>A layout export named headers() isn't a Next API and sends no headers. Render
the links instead; sonor-setup geo recognizes both supported discovery forms.
Step 3: robots.txt (required)
Name the AI crawlers explicitly with the kit's curated lists rather than a hand-rolled one, so a crawler the kit adds reaches every site on its next upgrade:
// app/robots.ts
import type { MetadataRoute } from 'next'
import { buildAiCrawlerRules } from '@sonordev/site-kit/llms'
export default function robots(): MetadataRoute.Robots {
return {
rules: [
{ userAgent: '*', allow: '/', disallow: ['/api/'] },
// Retrieval crawlers (they cite you) and training crawlers, each in its
// own group. training: 'block' keeps retrieval and opts out of training.
...buildAiCrawlerRules({ disallow: ['/api/'] }),
],
sitemap: 'https://example.com/sitemap.xml',
}
}A crawler that matches a named group ignores the * group, so pass the same
disallow to both. The lists are AI_RETRIEVAL_CRAWLERS and
AI_TRAINING_CRAWLERS. Don't keep a local list beside them; if an agent is
missing, add it to src/llms/aiRobots.ts.
Don't add a Content-Signal line (contentsignals.org). Google's robots.txt
parser reports it as an "Unknown directive" error in Search Console, and
robots.txt is the one file every crawler has to parse cleanly. Express the
same preference with buildAiCrawlerRules({ training: 'allow' | 'block' }).
createRobotsTxtHandler (a plain-text route handler) ignores
contentSignals since 6.3.4; remove it from a site's config when you next
touch the file.
These helpers are exported from @sonordev/site-kit/llms, their home.
@sonordev/site-kit/robots re-exports them too, beside createRobots: same
functions, either import works.
Step 4: Keep llms.txt out of the sitemap and the index
An XML sitemap lists indexable HTML pages. llms.txt is a plain-text restatement
of those pages, so listing it invites search engines to index a thin duplicate
of the site. AI crawlers don't need it listed: they fetch /llms.txt by
convention, and the Link: rel="describedby" discovery header points at it from
every page. Leave includeLlmsTxtInSitemap / includeLlmsFullTxtInSitemap off
(the default); sonor-setup geo warns when a sitemap lists them.
createLLMsTxtHandler and createLLMsFullTxtHandler send
X-Robots-Tag: noindex by default, which keeps the file out of search indexes
without stopping AI crawlers from fetching it. Pass noindex: false only if you
want it in search results.
A static public/llms.txt (the build-time write below) is served straight from
the CDN, so neither the handler nor next.config headers() ever sees it. Set the
header in host config instead:
# netlify.toml
[[headers]]
for = "/llms.txt"
[headers.values]
X-Robots-Tag = "noindex"
[[headers]]
for = "/llms-full.txt"
[headers.values]
X-Robots-Tag = "noindex"createSitemap({
baseUrl: 'https://example.com',
optimizedLLMsTxt: true, // Write build-time static file (default: true)
})The build-time write never persists a failure stub: if the Sonor fetch fails and no local data is available, writeLLMsTxtToPublic() skips the write (warning logged) so an existing public/llms.txt / public/llms-full.txt keeps serving via preferStatic.
Sonor generates this file with an LLM call that can take about a minute, and a prerendered route only gets 60s, so the in-route write often times out and keeps the previous file. For a refresh on every build, let the postbuild own it:
"scripts": { "postbuild": "sonor-register-sitemap --write-llms" }with optimizedLLMsTxt: false in createSitemap, so one writer owns the file.
Reads behind this write always bypass Next's Data Cache — hosts persist it
between builds, and a cached read is how a site shipped a months-old llms.txt.
Agent discovery for a custom MCP server
A custom server stays opt-in. Share the same mcp options between the
build-time writer and both route handlers so the short and full files point
at the same tools. This adds links to an existing server; it doesn't create
the endpoint, card, or catalog.
// lib/agent-access.ts
import type { AgentAccessOptions } from '@sonordev/site-kit/seo/llms'
export const agentAccess: AgentAccessOptions = {
endpoint: '/api/mcp',
card: '/api/mcp/server-card',
catalog: '/.well-known/ai-catalog.json', // omit unless this document is served
position: 'after-intro',
}// The site's build-time writer
import { writeLLMsTxtToPublic } from '@sonordev/site-kit/seo/llms'
import { agentAccess } from '../lib/agent-access'
await writeLLMsTxtToPublic({
full: true,
site: 'example.com',
mcp: agentAccess,
})// app/llms.txt/route.ts
import { createLLMsTxtHandler } from '@sonordev/site-kit/seo/llms'
import { agentAccess } from '@/lib/agent-access'
export const GET = createLLMsTxtHandler({
baseUrl: 'https://example.com',
mcp: agentAccess,
})// app/llms-full.txt/route.ts — use the same options
import { createLLMsFullTxtHandler } from '@sonordev/site-kit/seo/llms'
import { agentAccess } from '@/lib/agent-access'
export const GET = createLLMsFullTxtHandler({
baseUrl: 'https://example.com',
mcp: agentAccess,
})after-intro preserves the title and introduction and puts Agent access
before the first content section. end places it at the end. Existing
markdown that already contains Agent access or a recognized server-card link
is preserved, so update a site's existing discovery section directly when
its URLs change. The optional catalog is an experimental discovery document,
not a requirement for using the MCP endpoint.
The writer applies these options to both files, whether Sonor generated the
content or local data supplied it. It resolves the origin from
NEXT_PUBLIC_SITE_URL, falling back to the site host. The handlers apply
explicit options even when serving an older file through preferStatic;
they use baseUrl or the configured site URL and never read the incoming
request. A CDN serving public/llms.txt directly still needs the build-time
writer to update that file. mcp: false disables automatic insertion; it
doesn't remove a site's existing discovery text.
Step 5: On-Demand Revalidation (optional)
When Sonor data changes (page summaries, FAQs, etc.), bust the ISR cache instantly instead of waiting for s-maxage to expire:
// app/api/revalidate-llms/route.ts
import { createLlmsRevalidateHandler } from '@sonordev/site-kit/llms'
export const POST = createLlmsRevalidateHandler(process.env.REVALIDATION_SECRET!)Sonor can POST to this endpoint with Authorization: Bearer <secret> to revalidate /llms.txt and /llms-full.txt.
Sonor's SEO webhook (/api/seo-revalidate)
When a title, description or schema changes in Sonor, Sonor POSTs the
affected paths and cache tags to the site with the project key.
createSeoRevalidationHandler wraps the handler above and regenerates those
pages, /sitemap.xml and both llms files without a rebuild:
// app/api/seo-revalidate/route.ts
import { revalidatePath, revalidateTag } from 'next/cache'
import { createSeoRevalidationHandler } from '@sonordev/site-kit/llms'
export const runtime = 'nodejs'
export async function POST(request: Request) {
return createSeoRevalidationHandler({
secret: process.env.SONOR_API_KEY || '',
revalidatePath,
revalidateTag,
publicationBasePath: '/insights', // only when the site has a publication
})(request)
}- Auth is
Authorization: Bearer <SONOR_API_KEY>only, compared in constant time. No?secret=query form. - Body:
{ paths?, path?, tags?, tag?, revalidateAll? }, at most 16 KB and 100 paths/tags. Every path must be a same-site local path (no scheme,//, query, fragment,[segment]or dot segment, even percent-encoded). One bad entry refuses the whole call (400) before any cache is touched. revalidateAll, or a tag-only call carryingseo, also revalidates the root layout. Tags expire immediately ({ expire: 0 }).publicationBasePathrefreshes the publication index plusrss.xmlandfeed.xmlon every call, and maps legacy/blog/...paths to the same URL under the publication root, refreshing both.secretcan be a getter (() => process.env.SONOR_API_KEY), read on every call, so the handler can be created once at module scope.extraPathsare regenerated on every call.extendPayload(payload, body)adds paths or tags from body fields the handler doesn't read; its result is validated like the body.@sonordev/agency-site-kit/revalidateuses both for portfolio hubs,slug/slugsand its defaultportfoliotag.
llms.txt Generation
How generateLLMsTxt() Works
- Fetches all data via
getLLMsData()→GET /api/public/llms/data - Optionally merges with local data (
getLocalDatacallback) when Sonor returns nothing, leaves services, FAQs or pages empty, or leaves the business's name, description, phone or address empty. The merge is field by field: a field Sonor fills wins, and a field Sonor leaves empty never deletes the value the site supplied - Builds markdown sections in order: Header → About → Contact → Services → Site Pages → Portfolio → FAQ → Full Context Link → Knowledge Graph → Topic Clusters → Custom Sections → Agent access → Optional. The business and the contact block come first because they are short and answer the commonest question; the page index comes before the FAQ;
## Optionalis last because the spec lets a short-context reader stop there - Portfolio, Entity, and Topic Cluster sections are fetched in parallel via
Promise.allSettled() - Returns
{ markdown, metadata }where metadata includessections,attempted_sections, andfailed_sections
llms.txt Spec Compliance (llmstxt.org)
# Business Name
> Tagline or summary
> Content index last updated: 2026-04-08T00:00:00Z
> Primary language: en
> This information is provided for reference purposes only.
## About
Business description...
## Contact Information
- **Phone:** 555-0100
- **Email:** info@example.com
- **Address:** 123 Main St, Springfield, OH 45501
- **Hours:** Mon-Fri 8am-5pm
## Services
- [Service Name](https://example.com/services/slug): Brief description
## Site Pages
### Key pages
- [Home](https://example.com/): Public-safe summary of the page content
- [About](https://example.com/about): Learn about our team and mission
### Services
- [Furnace repair](https://example.com/services/furnace-repair): Same-day furnace repair in Springfield
## Portfolio & Case Studies
### [Project Title](https://example.com/work/project)
Description of the project.
## Frequently Asked Questions
### How do you work?
We follow a proven process...
## Full context
- [llms-full.txt](https://example.com/llms-full.txt): Expanded index for large-context systems.
## Knowledge Graph
### Business Name (Primary)
- **Type:** Organization
- **Schema:** LocalBusiness
## Topic Clusters
### Family Law Basics
Topic: Family Law
Area: Springfield
Articles: 8
Service page: https://example.com/services/family-law
Pillar: [Complete Guide to Family Law](/article/family-law-guide)
- [How to File for Divorce](/article/filing-divorce) (Mar 15, 2026)
- [Child Custody Laws](/article/custody-laws) (Mar 10, 2026)
## Optional
- [Privacy Policy](https://example.com/privacy): How we collect and use your informationConfiguration Options
generateLLMsTxt({
// Section toggles (all default to true)
includeBusinessInfo: true,
includeServices: true,
includeFAQ: true,
includePages: true,
includeContact: true,
includePortfolio: true,
includeEntities: true,
// Limits
maxFAQItems: 20, // default 20 (100 in full mode)
maxPages: 50, // default 50 (200 in full mode)
maxPortfolioItems: 20, // default 20 (50 in full mode)
maxEntities: 50, // default 50 (200 in full mode)
maxArticlesPerCluster: 5, // default 5
// Spec features
linkToFullLlms: true, // Append "Full context" section
optionalPagePaths: ['/privacy', '/terms'], // Moved from Site Pages to ## Optional
pageListNotesFromPublicSummaryOnly: false, // Strict mode: a note only from llms_public_summary
// Overrides (take precedence over Sonor settings)
headerPrimaryLanguage: 'en',
headerDisclaimer: 'This information is for reference purposes only.',
// Custom sections
customSections: [{ title: 'Specializations', content: 'We specialize in...' }],
// Local data fallback when Sonor is empty
getLocalData: async () => ({ business: {...}, services: [...], ... }),
})What a page line says
Every - [Title](url): note line is built by the same rules, in @sonordev/contracts/llms, wherever the file is generated.
The note, best source first (pickLlmsPageDescription):
- the page's
llms_public_summary, written for this file. A phone number or an email address in it is taken out along with the "call" or "email us at" in front of it, and the rest is used. (A summary used to be thrown away whole, and the page fell back to its scrape.) A lead-in such as "This page covers" is dropped, so the note starts at what the page is about; - the curated meta description (
managed_meta_description); - the meta description the page serves;
- the page's schema description;
- last, the page's scraped text, cleaned (
cleanScrapedPageText): the whitespace between elements put back, form labels, menu items, cookie banners and button text dropped, contact details removed.
Every note is cut at a sentence end or a word boundary, 500 characters at the most, and never mid-word. A note that only repeats the page's title, or whose text is an error page, is skipped. pageListNotesFromPublicSummaryOnly still limits notes to source 1.
The title is the curated title, else the title the page serves, else its h1, each without its | Brand tail; the home page is the business name; a page with none of these is named from the last segment of its path ("Accounting" for /features/accounting). It is never the raw path.
Which pages are listed. A page the last visit saw answer with an error, a page that asks search engines to leave it out (noindex), and a utility page (a cart, a thank-you page, a login) are left out, and each path is listed once.
Order and groups (groupLlmsPages). The home page first, then the top-level pages by value (what the site does, where, the proof, who, the cost, contact), then one ### group per section of the site (/services/* is "Services"), the biggest unlisted sections last, and the legal pages at the very end. A site of 12 pages or fewer is one list. When maxPages is smaller than the site, selectLlmsPages keeps every section represented, most valuable first, and the shorter list is always a subset of llms-full.txt.
Contact block. Phone, email, one-line address and hours. A field with nothing in it is not printed, and a contact with nothing at all leaves the whole section out.
The first line under the name is the tagline, else the first sentence of the description (not the text up to its first full stop, which cuts "Smith & Sons, Inc. is..." at "Inc").
Optional pages
optionalPagePaths demotes pages to ## Optional, the section llmstxt.org lets a
short-context parser skip. A matching page moves: it's removed from
## Site Pages and listed once under Optional with the same URL and note. The
filter runs before maxPages, so demoting a page frees an index slot for the next
one. /privacy, privacy and /privacy/ all match the same page. A path with no
matching page is still listed under Optional. The section needs a resolvable base
URL (see baseUrl); without one it's skipped and the pages stay in the index
rather than disappearing.
Metadata Returned
const { markdown, metadata } = await generateLLMsTxt({})
metadata.generated_at // ISO timestamp
metadata.project_id // From API key
metadata.sections // ['header', 'about', 'contact', 'services', 'pages', 'faq', ...]
metadata.attempted_sections // ['portfolio', 'knowledge-graph', 'topic-clusters']
metadata.failed_sections // ['knowledge-graph'] — if entity API was unavailableHTTP Caching
All llms.txt responses use this header strategy:
Content-Type: text/plain; charset=utf-8
Cache-Control: public, max-age=300, s-maxage=3600, stale-while-revalidate=86400, stale-if-error=86400
ETag: W/"<sha1-base64url>"
Vary: Accept-Encoding
- Browser: caches 5 minutes, then revalidates
- CDN: caches 1 hour, serves stale for 24 hours while revalidating
- 304 support: The Next static layer / CDN matches
If-None-Matchagainst the emitted ETag. The handlers themselves never read request headers — doing so would force the route dynamic and break static prerendering
The llmsResponseHeaders(body, extra?) helper is exported for custom route handlers.
JSON-LD Integration
LLMSchema (via ManagedSchema)
The LLMSchema component in @sonordev/site-kit/seo emits managed_llm_schema from Sonor as JSON-LD:
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "WebPage",
"name": "Divorce Law",
"description": "Comprehensive divorce representation...",
"url": "https://example.com/divorce",
"additionalType": "https://sonor.io/ns/LLMOptimizedContent",
"isPartOf": {
"@type": "WebSite",
"@id": "https://example.com/#website",
"url": "https://example.com"
}
}
</script>managed_llm_schemais generated by Signal AI during SEO meta optimization- Only known keys from
MANAGED_LLM_SCHEMA_KNOWN_KEYSare emitted (safety filter) isPartOfuses a stable@idpattern:${siteUrl}/#website
Organization Stub
createWebSiteOrganizationStub() from @sonordev/site-kit/seo creates paired Organization + WebSite entities for @graph injection with stable @id anchors (/#organization, /#website).
AEO Components
Semantic HTML components with schema.org microdata and data-sonor-* attributes for AI extraction.
| Component | Schema Type | Use Case |
|---|---|---|
AEOBlock | Question/Answer | FAQ-style Q&A content |
AEOSummary | — | Key points lists (speakable) |
AEODefinition | DefinedTerm | Term/definition pairs |
AEOSteps / AEOStep | HowTo | Step-by-step processes |
AEOComparison | — | Feature/option comparison tables |
AEOClaim | Claim | Source-attributed factual claims |
AEOEntity | — | Inline entity annotations |
AEOProvenanceList | — | Citation source lists |
AEOCitedContent | — | Content with numbered citations |
All components support:
speakableprop → addsdata-speakable="true"for voice assistantsentityIdprop → links to knowledge graph viadata-sonor-entityclassNameprop → custom styling
Example: Service Page with AEO
import { AEOSummary, AEOSteps, AEOStep, AEOBlock } from '@sonordev/site-kit/llms'
export default function DivorcePage() {
return (
<article>
<h1>Divorce Law Services</h1>
<AEOSummary
title="Key Facts"
points={[
'25+ years of family law experience',
'Serving Springfield and the surrounding counties',
'Free initial consultation available',
]}
speakable
/>
<AEOSteps title="The Divorce Process" speakable>
<AEOStep name="Consultation" text="Meet with attorney to discuss your situation" position={1} />
<AEOStep name="File Petition" text="Submit divorce petition to circuit court" position={2} />
<AEOStep name="Negotiate" text="Work toward fair settlement" position={3} />
<AEOStep name="Finalize" text="Court issues final decree" position={4} />
</AEOSteps>
<AEOBlock type="answer" question="How long does a divorce take?" speakable>
Uncontested divorces typically take 60-90 days. Contested cases take 6-12 months.
</AEOBlock>
</article>
)
}Speakable Schema
Marks page sections for voice assistant extraction via SpeakableSpecification JSON-LD.
import { SpeakableSchema } from '@sonordev/site-kit/llms'
<SpeakableSchema
type="WebPage"
name="Divorce Law"
url="https://example.com/divorce"
speakable={{ cssSelectors: ['h1', '[data-speakable="summary"]'] }}
/>Default selectors by page type:
| Type | Selectors |
|---|---|
page | h1, [data-speakable], .intro, [role="main"] > p:first-of-type |
article | h1, .article-summary, article > p:first-of-type, [data-speakable] |
service | h1, .service-description, [data-speakable="summary"] |
faq | .faq-question, [data-speakable] |
contact | h1, .contact-info, [itemprop="address"] |
Sonor API Endpoints
Public (API key auth via x-api-key)
| Endpoint | Purpose |
|---|---|
GET /api/public/llms/data | All LLM visibility data (business, services, FAQ, pages, meta) |
GET /api/public/llms/txt | AI-optimized llms.txt markdown (calls Signal AEO, with fallback) |
GET /api/public/llms/txt?full=true | Extended version (200 pages, 100 FAQ) |
GET /api/public/llms/txt?publicSummaryOnly=true | Strict mode: page notes from llms_public_summary only |
GET /api/public/llms/business | Business info only |
GET /api/public/llms/services | Services list |
GET /api/public/llms/faq | FAQ items (getFAQItems(projectId?, limit?, site?) sends ?site=, so a microsite gets its own FAQs plus project-wide ones) |
GET /api/public/llms/pages | Page summaries |
Authenticated (dashboard)
| Endpoint | Purpose |
|---|---|
GET /seo/projects/:id/llms/preview | Preview llms.txt markdown + stats |
GET /seo/projects/:id/llms/analytics?period=7 | AI crawler request breakdown |
Key Database Fields
| Table | Column | Purpose |
|---|---|---|
seo_pages | llms_public_summary | Public-safe summary for llms.txt link notes (max 400 chars) |
seo_pages | managed_llm_schema | JSON-LD object for per-page LLM optimization |
seo_pages | language_alternates | Optional hreflang map (locale → URL) |
seo_pages | llm_schema_generated_at | When Signal last generated the schema |
projects.settings | primary_language | BCP 47 tag for llms.txt blockquote |
projects.settings | llms_disclaimer | Optional disclaimer line in blockquote |
llms_request_log | bot_class | AI crawler classification for analytics |
Environment Variables
# Required (server-only — SiteKitLayout injects into client automatically):
SONOR_API_KEY=sonor_xxxxxxxx_xxxxx
# Optional:
SONOR_API_URL=https://api.sonor.io # Default
NEXT_PUBLIC_SITE_URL=https://example.com # For CLI status checks
REVALIDATION_SECRET=your_secret # For on-demand revalidation endpointCLI Validation
npx sonor-setup status runs a comprehensive llms.txt health check when NEXT_PUBLIC_SITE_URL is set:
- HTTP status — must be 200
- Content structure — H1 title, blockquote summary, H2 section count
- Response headers — Content-Type, Cache-Control (s-maxage), ETag presence
- Freshness — parses
last_updatedfrom blockquote, warns if > 7 days old
Exports
// Types
import type {
LLMBusinessInfo, LLMContactInfo, LLMService, LLMFAQItem,
LLMPageSummary, LLMPortfolioItem, LLMsDataResponse, LLMsPayloadMeta,
GenerateLLMSTxtOptions, LLMSTxtContent, WriteLLMsTxtOptions,
SpeakableConfig, SpeakableSchemaProps,
AEOBlockProps, AEOSummaryProps, AEODefinitionProps,
AEOClaimProps, AEOEntityProps, ContentProvenance,
AEOProvenanceListProps, AEOCitedContentProps,
AiDiscoveryHeadersOptions, LlmsLanguageAlternate,
} from '@sonordev/site-kit/llms'
// Contract (lightweight — safe for API imports)
import {
LLM_GEO_CONTRACT_VERSION, LLMS_PUBLIC_SUMMARY_MAX_LENGTH,
LLMS_DISCLAIMER_MAX_LENGTH, MANAGED_LLM_SCHEMA_KNOWN_KEYS,
sanitizeLlmsPublicSummary, sanitizeLlmsDisclaimerLine,
sanitizePrimaryLanguageTag, pickManagedLlmSchemaForJsonLd,
} from '@sonordev/site-kit/llms/contract'
// Generation
import { generateLLMsTxt, generateLLMsFullTxt } from '@sonordev/site-kit/llms'
// Route handlers
import {
createLLMsTxtHandler, createLLMsFullTxtHandler, llmsResponseHeaders,
} from '@sonordev/site-kit/llms'
// Discovery: HTML for Next layouts, HTTP for controlled response merging
import { AiDiscoveryLinks } from '@sonordev/site-kit/layout'
import { buildAiDiscoveryHeaders } from '@sonordev/site-kit/llms'
// API data fetchers (React cache()-wrapped)
import {
getLLMsData, getBusinessInfo, getServices, getFAQItems,
getPageSummaries, getOptimizedLLMsTxt,
} from '@sonordev/site-kit/llms'
// Build-time
import { writeLLMsTxtToPublic } from '@sonordev/site-kit/llms'
// Revalidation
import { createLlmsRevalidateHandler } from '@sonordev/site-kit/llms'
// Speakable
import {
SpeakableSchema, createSpeakableSchema,
getSpeakableSelectorsForPage, DEFAULT_SPEAKABLE_SELECTORS,
} from '@sonordev/site-kit/llms'
// AEO Components
import {
AEOBlock, AEOSummary, AEODefinition, AEOSteps, AEOStep,
AEOComparison, AEOClaim, AEOEntity, AEOProvenanceList, AEOCitedContent,
} from '@sonordev/site-kit/llms'
// Proxy (separate import path)
import { createProxy } from '@sonordev/site-kit/proxy'
// Config type: { llmsDiscovery?: { siteUrl: string; llmsPath?: string } | false }Testing
# Run all llms tests (42 tests across 4 suites)
pnpm test src/llms/
# Test suites:
# - contract.test.ts — sanitizers, PII filtering, schema key allowlist
# - generateLLMsTxt.test.ts — generation: sections, limits, flags, fallbacks, metadata
# - handlers.test.ts — response headers, ETag, Cache-Control
# - discovery-headers.test.ts — Link header format, hreflang validationManual verification
# Check llms.txt
curl -s https://example.com/llms.txt | head -20
# Check headers
curl -sI https://example.com/llms.txt | grep -E 'ETag|Cache-Control|Content-Type|Link'
# Check discovery Link header on HTML page
curl -sI -H 'Accept: text/html' https://example.com/ | grep Link
# Check 304 support (served by the CDN/static layer, not the handler)
ETAG=$(curl -sI https://example.com/llms.txt | grep ETag | awk '{print $2}' | tr -d '\r')
curl -sI -H "If-None-Match: $ETAG" https://example.com/llms.txt | head -1
# Should return: HTTP/2 304