+-----------------------------------------------------------------------------------+
|                        DYNAMIC /LLMS.TXT GENERATION PIPELINE                      |
|                                                                                   |
|  [ 1. INCOMING AI REQUEST ] ──> GET https://example.com/llms.txt                  |
|                                         │                                         |
|                                         ▼                                         |
|  [ 2. NEXT.JS 15 APP ROUTER HANDLER (app/llms.txt/route.ts) ] ─────────────────── |
|  * Fetches latest published posts, API specs, and documentation via CMS/DB.       |
|  * Formats into standard /llms.txt H1/H2 Markdown hierarchy with bullet links.    |
|                                │                                                  |
|                                ▼                                                  |
|  [ 3. EDGE ISR CACHE LAYER (s-maxage=3600, stale-while-revalidate) ] ─────────── |
|  * Caches compiled Markdown on edge CDN nodes globally.                           |
|  * Sub-25ms response time for AI scrapers (OAI-SearchBot, ClaudeBot, etc.)!       |
|                                │                                                  |
|                                ▼                                                  |
|  [ 4. OPTIONAL /LLMS-FULL.TXT STREAMING (Complete Inlined Corpus) ] ───────────── |
|  * Appends full inlined Markdown content for deep-context IDE ingestion (Cursor).|
+-----------------------------------------------------------------------------------+

// app/llms.txt/route.ts
import { NextResponse } from 'next/server';
import { getAllPublishedPosts, getCoreDocumentationPages } from '@/lib/content';

export const runtime = 'edge'; // Execute on global edge network for sub-30ms TTFB
export const revalidate = 3600; // Invalidate cache hourly

export async function GET() {
  const posts = await getAllPublishedPosts();
  const docs = await getCoreDocumentationPages();

  let markdown = `# BugViso AI Documentation\n\n`;
  markdown += `> BugViso is a modern website quality assurance and Generative Engine Optimization (GEO) audit platform. It analyzes Core Web Vitals under throttled mobile 3G emulation, audits automated WCAG 2.1 AA accessibility, and scores machine citability for AI answer engines.\n\n`;

  // 1. Core Platform Documentation Section
  markdown += `## Documentation & Developer Guides\n\n`;
  for (const doc of docs) {
    markdown += `- [${doc.title}](${doc.url}): ${doc.description}\n`;
  }
  markdown += `\n`;

  // 2. Latest Technical Articles & Case Studies
  markdown += `## Technical Knowledge Base & Case Studies\n\n`;
  for (const post of posts) {
    markdown += `- [${post.title}](https://bugviso.com/blog/${post.slug}): ${post.description}\n`;
  }
  markdown += `\n`;

  // 3. Optional Section for Deep Context
  markdown += `## Optional\n\n`;
  markdown += `- [Full Documentation Corpus](https://bugviso.com/llms-full.txt): Complete inlined Markdown documentation for IDE context and Claude Projects.\n`;

  return new NextResponse(markdown, {
    status: 200,
    headers: {
      'Content-Type': 'text/plain; charset=utf-8',
      'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=86400',
    },
  });
}

// app/llms-full.txt/route.ts
import { NextResponse } from 'next/server';
import { getAllPublishedPosts } from '@/lib/content';

export const runtime = 'edge';
export const revalidate = 7200; // Cache for 2 hours

export async function GET() {
  const posts = await getAllPublishedPosts();

  let corpus = `# BugViso Complete Inlined Technical Corpus\n\n`;
  corpus += `This document contains the complete Markdown text of all technical articles, guides, and API specifications.\n\n`;

  for (const post of posts) {
    corpus += `================================================================================\n`;
    corpus += `DOCUMENT: ${post.title}\n`;
    corpus += `URL: https://bugviso.com/blog/${post.slug}\n`;
    corpus += `CATEGORY: ${post.category}\n`;
    corpus += `================================================================================\n\n`;
    corpus += `${post.rawMarkdownContent}\n\n`;
  }

  return new NextResponse(corpus, {
    status: 200,
    headers: {
      'Content-Type': 'text/plain; charset=utf-8',
      'Cache-Control': 'public, s-maxage=7200, stale-while-revalidate=86400',
    },
  });
}

// app/api/revalidate-llms/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { revalidatePath } from 'next/cache';

export async function POST(request: NextRequest) {
  const secret = request.nextUrl.searchParams.get('secret');

  if (secret !== process.env.REVALIDATION_SECRET_TOKEN) {
    return NextResponse.json({ message: 'Invalid secret token' }, { status: 401 });
  }

  // Purge edge cache for both LLM manifest routes
  revalidatePath('/llms.txt');
  revalidatePath('/llms-full.txt');

  return NextResponse.json({
    revalidated: true,
    timestamp: new Date().toISOString(),
  });
}

// lib/markdown-serializer.ts
export interface ContentDoc {
  title: string;
  slug: string;
  description: string;
  category: string;
  body: string;
}

export function serializeToCleanMarkdown(doc: ContentDoc): string {
  let cleanBody = doc.body;

  // 1. Convert HTML headings to Markdown if present
  cleanBody = cleanBody.replace(/<h1>(.*?)<\/h1>/gi, '# $1\n\n');
  cleanBody = cleanBody.replace(/<h2>(.*?)<\/h2>/gi, '## $1\n\n');
  cleanBody = cleanBody.replace(/<h3>(.*?)<\/h3>/gi, '### $1\n\n');

  // 2. Strip interactive script, iframe, and svg noise
  cleanBody = cleanBody.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '');
  cleanBody = cleanBody.replace(/<svg\b[^<]*(?:(?!<\/svg>)<[^<]*)*<\/svg>/gi, '');

  // 3. Ensure consistent code block formatting
  cleanBody = cleanBody.trim();

  return `# ${doc.title}\n\n> ${doc.description}\n\n${cleanBody}`;
}

# robots.txt
User-agent: *
Allow: /

# LLM Documentation Manifests
Sitemap: https://example.com/sitemap.xml
# /llms.txt is served at https://example.com/llms.txt

+-----------------------------------------------------------------------------------+
|                        BUGVISO LLMS.TXT AUDITING ENGINE                           |
|                                                                                   |
|  [ Web Application Submitted ] ──> [ FastAPI + ARQ Redis Worker Cluster ]         |
|                                         │                                         |
|                                         ▼                                         |
|  [ 4-STAGE LLMS.TXT VALIDATION PIPELINE ] ──────────────────────────────────────  |
|  ├── 1. Endpoint Resolution QA: Tests HTTP 200 OK and text/plain MIME headers      |
|  ├── 2. Markdown Syntax Linter: Verifies H1 title, summary, and bullet link syntax|
|  ├── 3. Broken Link Verifier: Checks 100% of declared markdown URLs for dead links|
|  └── 4. GEO Citability Engine: Evaluates /llms.txt and AI crawler permissions      |
|                                         │                                         |
|                                         ▼                                         |
|  [ COMPOSITE 0-100 GEO SCORE + ACTIONABLE DEVELOPER REMEDIATION PLAYBOOK ]        |
+-----------------------------------------------------------------------------------+