GEO Module — @sonordev/site-kit/llms

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
├─ createProxy({ llmsDiscovery }) ← sends the Link header from proxy.ts
├─ 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)
├─ Link header       ← rel="describedby" on all HTML responses
├─ robots.txt        ← allows AI crawlers to access /llms.txt
└─ JSON-LD in <head> ← managed_llm_schema per page

// 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 = 3600

// proxy.ts
import { createProxy } from '@sonordev/site-kit/proxy'

export default createProxy({
  llmsDiscovery: { siteUrl: 'https://example.com' },
})

// Inlined: an imported `config.matcher` is a build error. See the proxy README.
export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon\\.ico|.*\\.(?:ico|png|jpg|jpeg|gif|webp|svg|woff2?)$).*)',
  ],
}

// next.config.ts
import { withSiteKitConfig } from '@sonordev/site-kit/config'

export default withSiteKitConfig({ llmsTxtDiscoveryLink: true })

buildAiDiscoveryHeaders({
  siteUrl: 'https://example.com',
  languageAlternates: [
    { hreflang: 'fr', href: 'https://example.com/fr/llms.txt' },
  ],
})

// 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',
  }
}

# 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)
})

"scripts": { "postbuild": "sonor-register-sitemap --write-llms" }

// app/api/revalidate-llms/route.ts
import { createLlmsRevalidateHandler } from '@sonordev/site-kit/llms'
export const POST = createLlmsRevalidateHandler(process.env.REVALIDATION_SECRET!)

// 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)
}

# 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...

## Services

- [Service Name](/services/slug): Brief description

## Portfolio & Case Studies

### [Project Title](https://example.com/work/project)

Description of the project.

## Contact Information

- **Phone:** 555-1234
- **Email:** info@example.com
- **Address:** 123 Main St, City, State

## Frequently Asked Questions

### How do you work?

We follow a proven process...

## Site Pages

- [Home](https://example.com/): Public-safe summary of the page content
- [About](https://example.com/about): Learn about our team and mission

## Optional

- [Privacy Policy](https://example.com/privacy): How we collect and use your information

## 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)

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: no description fallback

  // 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: [...], ... }),
})

const { markdown, metadata } = await generateLLMsTxt({})

metadata.generated_at      // ISO timestamp
metadata.project_id        // From API key
metadata.sections          // ['header', 'about', 'services', 'faq', 'pages', ...]
metadata.attempted_sections // ['portfolio', 'knowledge-graph', 'topic-clusters']
metadata.failed_sections   // ['knowledge-graph'] — if entity API was unavailable

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

<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>

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>
  )
}

import { SpeakableSchema } from '@sonordev/site-kit/llms'

<SpeakableSchema
  type="WebPage"
  name="Divorce Law"
  url="https://example.com/divorce"
  speakable={{ cssSelectors: ['h1', '[data-speakable="summary"]'] }}
/>

# 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 endpoint

// 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
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 }

# 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 validation

# 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