From 920c5f0ca2482ec56cfc0f7f6dd2859943274739 Mon Sep 17 00:00:00 2001
From: Gabriel Barros <gbbabarros@gmail.com>
Date: Fri, 22 May 2026 10:13:43 -0300
Subject: [PATCH 1/3] Improve docs AI readiness assets

---
 .gitignore               |   7 +
 app/layout.tsx           | 113 +++++++++++++-
 scripts/generate-llms.js | 323 ++++++++++++++++++++++++++++++++++-----
 3 files changed, 403 insertions(+), 40 deletions(-)

diff --git a/.gitignore b/.gitignore
index 0f1fffd8970..c0a76da121f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -46,4 +46,11 @@ _pagefind/
 # agents llms
 AGENTS.md
 /public/llms.txt
+/public/llms-full.txt
+/public/**/*.md
+!/public/SKILL.md
+/public/**/llms.txt
+/public/robots.txt
+/public/sitemap.xml
+/public/.well-known/
 package-lock.json
diff --git a/app/layout.tsx b/app/layout.tsx
index 8d4b124174e..e1e48402576 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -6,6 +6,10 @@ import "nextra-theme-docs/style.css";
 import "katex/dist/katex.min.css";
 import { FontStyles } from "@/components/FontStyles";
 
+const SITE_ORIGIN = "https://docs.celestia.org";
+const SITE_DESCRIPTION =
+  "Learn, build, and operate on Celestia - the modular data availability network.";
+
 // Use BASE env var (same as next.config.mjs) and ensure it's available client-side
 const basePath =
   process.env.NEXT_PUBLIC_BASE_PATH ||
@@ -23,10 +27,90 @@ const THEME_CONFIG = {
   primarySaturation: 100,
 };
 export const metadata = {
-  // Define your metadata here
-  // For more information on metadata API, see: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
+  metadataBase: new URL(SITE_ORIGIN),
+  title: {
+    default: "Celestia Documentation",
+    template: "%s - Celestia Documentation",
+  },
+  description: SITE_DESCRIPTION,
+  alternates: {
+    canonical: "/",
+  },
+  openGraph: {
+    type: "website",
+    url: SITE_ORIGIN,
+    siteName: "Celestia Documentation",
+    title: "Celestia Documentation",
+    description: SITE_DESCRIPTION,
+    images: [
+      {
+        url: "/Celestia-og.png",
+        width: 1200,
+        height: 630,
+        alt: "Celestia Documentation",
+      },
+    ],
+  },
+  twitter: {
+    card: "summary_large_image",
+    site: "@CelestiaOrg",
+    title: "Celestia Documentation",
+    description: SITE_DESCRIPTION,
+    images: ["/Celestia-og.png"],
+  },
+  robots: {
+    index: true,
+    follow: true,
+    googleBot: {
+      index: true,
+      follow: true,
+    },
+  },
+};
+
+const organizationJsonLd = {
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  name: "Celestia",
+  url: "https://celestia.org",
+  logo: `${SITE_ORIGIN}/logo-light.svg`,
+  sameAs: [
+    "https://github.com/celestiaorg",
+    "https://x.com/CelestiaOrg",
+    "https://discord.com/invite/YsnTPcSfWQ",
+  ],
+};
+
+const websiteJsonLd = {
+  "@context": "https://schema.org",
+  "@type": "WebSite",
+  name: "Celestia Documentation",
+  url: SITE_ORIGIN,
+  description: SITE_DESCRIPTION,
+};
+
+const documentationJsonLd = {
+  "@context": "https://schema.org",
+  "@type": "TechArticle",
+  headline: "Celestia Documentation",
+  description: SITE_DESCRIPTION,
+  url: SITE_ORIGIN,
+  publisher: {
+    "@type": "Organization",
+    name: "Celestia",
+    url: "https://celestia.org",
+  },
+  about: [
+    "Celestia",
+    "data availability",
+    "modular blockchain",
+    "blobspace",
+    "node operation",
+  ],
 };
 
+const jsonLd = [organizationJsonLd, websiteJsonLd, documentationJsonLd];
+
 const banner = (
   <Banner storageKey="some-key">Welcome to our new docs! 🎉</Banner>
 );
@@ -86,8 +170,31 @@ export default async function RootLayout({
         <meta property="og:title" content="Celestia Documentation" />
         <meta
           property="og:description"
-          content="Learn, build, and operate on Celestia - the first modular blockchain network."
+          content={SITE_DESCRIPTION}
+        />
+        <link rel="alternate" type="text/plain" href={withBasePath("/llms.txt")} />
+        <link
+          rel="alternate"
+          type="text/plain"
+          href={withBasePath("/llms-full.txt")}
+        />
+        <link
+          rel="service-desc"
+          type="application/linkset+json"
+          href={withBasePath("/.well-known/api-catalog")}
+        />
+        <link
+          rel="describedby"
+          type="application/json"
+          href={withBasePath("/.well-known/agent-skills/index.json")}
         />
+        {jsonLd.map((data, index) => (
+          <script
+            key={index}
+            type="application/ld+json"
+            dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }}
+          />
+        ))}
       </Head>
       <body>
         <Layout
diff --git a/scripts/generate-llms.js b/scripts/generate-llms.js
index 741db60bfef..a258cf882dc 100644
--- a/scripts/generate-llms.js
+++ b/scripts/generate-llms.js
@@ -3,8 +3,11 @@
 import { promises as fs } from 'fs';
 import path from 'path';
 import { createRequire } from 'module';
+import { createHash } from 'crypto';
 
-const RAW_BASE = 'https://raw.githubusercontent.com/celestiaorg/docs/main/';
+const SITE_ORIGIN = 'https://docs.celestia.org';
+const GITHUB_REPO = 'https://github.com/celestiaorg/docs';
+const LATEST_OPENRPC_SPEC = '/specs/openrpc-v0.28.4.json';
 
 // Use createRequire to import JSON files in ESM context
 const require = createRequire(import.meta.url);
@@ -89,6 +92,10 @@ function replaceVariables(text) {
   // First replace {{...}} patterns (double braces)
   text = text.replace(/\{\{([^{}]+)\}\}/g, (match, expression) => {
     const trimmedExpr = expression.trim();
+    if (!/^(mainnetVersions|mochaVersions|arabicaVersions|constants)(?:\[['"][^'"]+['"]\]|\.\w+)$/.test(trimmedExpr)) {
+      return match;
+    }
+
     const resolved = resolveExpression(trimmedExpr);
 
     if (resolved !== null) {
@@ -149,10 +156,22 @@ const header = [
   '',
   '> Official documentation for Celestia, the modular blockchain powering unstoppable apps with full-stack control.',
   '',
-  'These docs are built with Next.js + Nextra and exported statically. Links below point to the raw MDX sources in `main` so tools and LLMs can ingest clean text.',
+  'These docs are built with Next.js + Nextra and exported statically. Links below point to canonical markdown pages so tools and LLMs can ingest clean text.',
+  '',
+  '## Agent instructions',
+  '',
+  '- Prefer the `.md` pages linked here for retrieval and citations.',
+  '- Use `llms-full.txt` when a single-file context snapshot is needed.',
+  '- Use `/build/llms.txt`, `/learn/llms.txt`, and `/operate/llms.txt` for section-specific context.',
+  '- Celestia does not currently publish an official MCP server for this documentation site.',
   '',
   '## Related resources',
   '',
+  '- Full LLM context: https://docs.celestia.org/llms-full.txt',
+  '- Agent skill: https://docs.celestia.org/SKILL.md',
+  '- Agent skills index: https://docs.celestia.org/.well-known/agent-skills/index.json',
+  '- API catalog: https://docs.celestia.org/.well-known/api-catalog',
+  '- Node API OpenRPC spec: https://docs.celestia.org/specs/openrpc-v0.28.4.json',
   '- CIPs (Celestia Improvement Proposals): https://cips.celestia.org',
 ];
 
@@ -163,7 +182,52 @@ const titleize = (segment) =>
     .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
     .join(' ');
 
-const formatItem = (path, label) => `- [${label}](${RAW_BASE}${path})`;
+const toPosixPath = (filePath) => filePath.split(path.sep).join('/');
+
+const markdownPathForFile = (file) => {
+  let outputPath = toPosixPath(file).replace(/^app\//, '').replace(/\.mdx$/, '.md');
+
+  if (outputPath.endsWith('/page.md')) {
+    outputPath = outputPath.replace(/\/page\.md$/, '.md');
+  } else if (outputPath === 'page.md') {
+    outputPath = 'index.md';
+  }
+
+  return outputPath;
+};
+
+const htmlPathForFile = (file) => {
+  const rel = toPosixPath(file).replace(/^app\//, '');
+
+  if (rel === 'page.mdx') return '/';
+  if (!rel.endsWith('/page.mdx')) return null;
+
+  return `/${rel.replace(/\/page\.mdx$/, '/')}`;
+};
+
+const canonicalUrl = (pathname) => `${SITE_ORIGIN}${pathname}`;
+
+const canonicalMarkdownUrl = (file) => `${SITE_ORIGIN}/${markdownPathForFile(file)}`;
+
+const formatItem = (file, label) => `- [${label}](${canonicalMarkdownUrl(file)})`;
+
+const escapeXml = (value) =>
+  value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+
+const extractTitle = (content, fallback) => {
+  const heading = content.match(/^#\s+(.+)$/m);
+  return heading ? heading[1].trim() : fallback;
+};
+
+const sha256 = async (file) => {
+  const content = await fs.readFile(file);
+  return createHash('sha256').update(content).digest('hex');
+};
 
 const walkPages = async (dir) => {
   const pages = [];
@@ -179,13 +243,11 @@ const walkPages = async (dir) => {
   return pages;
 };
 
-const buildSections = async () => {
-  const files = (await walkPages('app')).sort();
-
+const buildSections = (files) => {
   const grouped = new Map();
 
   for (const file of files) {
-    const rel = file.replace(/^app\//, '');
+    const rel = toPosixPath(file).replace(/^app\//, '');
     const parts = rel.split('/');
     if (parts.length < 2) continue; // skip unexpected roots
 
@@ -199,39 +261,29 @@ const buildSections = async () => {
     const label = labelSegments.map(titleize).join(' / ');
 
     if (!grouped.has(sectionTitle)) grouped.set(sectionTitle, []);
-    grouped.get(sectionTitle).push({ path: file, label });
+    grouped.get(sectionTitle).push({ file, label });
   }
 
   // Sort sections and items for stability
   const sortedSections = [...grouped.entries()].sort(([a], [b]) => a.localeCompare(b));
   return sortedSections.map(([title, items]) => ({
     title,
-    items: items.sort((a, b) => a.path.localeCompare(b.path)),
+    items: items.sort((a, b) => a.file.localeCompare(b.file)),
   }));
 };
 
-const generateMarkdownFiles = async (outputBase) => {
+const generateMarkdownFiles = async (outputBase, files) => {
   console.log('🤖 Generating LLM-ready markdown files...');
 
-  // Find all MDX files
-  const files = await walkPages('app');
-
   console.log(`Found ${files.length} MDX files to convert`);
   console.log(`Writing markdown files to: ${outputBase}/`);
 
+  const pages = [];
+
   for (const file of files) {
     const content = await fs.readFile(file, 'utf-8');
     const cleanedContent = cleanMdxContent(content);
-
-    // Determine output path
-    let outputPath = file.replace(/^app\//, '').replace(/\.mdx$/, '.md');
-
-    // Handle page.mdx files - they should become index.md
-    if (outputPath.endsWith('/page.md')) {
-      outputPath = outputPath.replace(/\/page\.md$/, '.md');
-    } else if (outputPath === 'page.md') {
-      outputPath = 'index.md';
-    }
+    const outputPath = markdownPathForFile(file);
 
     const outputFullPath = path.join(outputBase, outputPath);
 
@@ -242,34 +294,231 @@ const generateMarkdownFiles = async (outputBase) => {
     // Write the cleaned markdown file
     await fs.writeFile(outputFullPath, cleanedContent, 'utf-8');
     console.log(`✅ Generated: ${outputPath}`);
+
+    pages.push({
+      file,
+      markdownPath: outputPath,
+      markdownUrl: canonicalMarkdownUrl(file),
+      htmlPath: htmlPathForFile(file),
+      content: cleanedContent,
+      title: extractTitle(cleanedContent, titleize(path.basename(path.dirname(file)))),
+    });
   }
-};
 
-const main = async () => {
-  // Determine output directory once - use 'out' if it exists (during build), otherwise 'public' (during dev)
-  const outputBase = await fs.access('out').then(() => 'out').catch(() => 'public');
+  return pages;
+};
 
-  // Generate individual markdown files
-  await generateMarkdownFiles(outputBase);
+const writeTextFile = async (outputBase, filePath, content) => {
+  const outputFullPath = path.join(outputBase, filePath);
+  await fs.mkdir(path.dirname(outputFullPath), { recursive: true });
+  await fs.writeFile(outputFullPath, content, 'utf8');
+};
 
-  // Also generate the index file
-  const sections = await buildSections();
+const generateLlmsTxt = async (outputBase, sections, filePath = 'llms.txt') => {
   const lines = [...header, ''];
   sections.forEach((section) => {
     if (!section.items.length) return;
     lines.push(`## ${section.title}`, '');
-    section.items.forEach((item) => lines.push(formatItem(item.path, item.label)));
+    section.items.forEach((item) => lines.push(formatItem(item.file, item.label)));
     lines.push('');
   });
 
   const output = lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+  await writeTextFile(outputBase, filePath, output);
+};
 
-  // Write llms.txt to the appropriate directory
-  await fs.mkdir(outputBase, { recursive: true });
-  await fs.writeFile(path.join(outputBase, 'llms.txt'), output, 'utf8');
+const generateSectionLlmsTxt = async (outputBase, sections) => {
+  for (const topLevel of ['build', 'learn', 'operate']) {
+    const sectionPrefix = `${titleize(topLevel)}: `;
+    const sectionItems = sections.filter((section) => section.title.startsWith(sectionPrefix));
+    const lines = [
+      `# Celestia ${titleize(topLevel)} documentation`,
+      '',
+      `> Section-specific LLM index for the ${titleize(topLevel)} area of the Celestia docs.`,
+      '',
+      '- Full docs index: https://docs.celestia.org/llms.txt',
+      '- Full LLM context: https://docs.celestia.org/llms-full.txt',
+      '',
+    ];
+
+    sectionItems.forEach((section) => {
+      lines.push(`## ${section.title.replace(sectionPrefix, '')}`, '');
+      section.items.forEach((item) => lines.push(formatItem(item.file, item.label)));
+      lines.push('');
+    });
+
+    await writeTextFile(outputBase, `${topLevel}/llms.txt`, lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n');
+  }
+};
+
+const generateLlmsFullTxt = async (outputBase, pages) => {
+  const lines = [
+    '# Celestia documentation full context',
+    '',
+    '> Full cleaned markdown export of the Celestia documentation for LLM and agent ingestion.',
+    '',
+  ];
+
+  pages
+    .filter((page) => page.content)
+    .sort((a, b) => a.markdownPath.localeCompare(b.markdownPath))
+    .forEach((page) => {
+      lines.push('---');
+      lines.push(`Title: ${page.title}`);
+      lines.push(`URL: ${page.markdownUrl}`);
+      lines.push(`Source: ${toPosixPath(page.file)}`);
+      lines.push('---');
+      lines.push('');
+      lines.push(page.content);
+      lines.push('');
+    });
+
+  await writeTextFile(outputBase, 'llms-full.txt', lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n');
+};
+
+const generateSitemap = async (outputBase, pages) => {
+  const urls = pages
+    .map((page) => page.htmlPath)
+    .filter(Boolean)
+    .sort()
+    .map((pathname) => `  <url>\n    <loc>${escapeXml(canonicalUrl(pathname))}</loc>\n  </url>`);
+
+  const sitemap = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    ...urls,
+    '</urlset>',
+    '',
+  ].join('\n');
+
+  await writeTextFile(outputBase, 'sitemap.xml', sitemap);
+};
+
+const generateRobotsTxt = async (outputBase) => {
+  const aiBots = [
+    'GPTBot',
+    'OAI-SearchBot',
+    'ClaudeBot',
+    'Claude-Web',
+    'Google-Extended',
+    'PerplexityBot',
+    'CCBot',
+  ];
+
+  const lines = [
+    'User-agent: *',
+    'Allow: /',
+    '',
+    ...aiBots.flatMap((bot) => [`User-agent: ${bot}`, 'Allow: /', '']),
+    'Content-Signal: ai-train=yes, search=yes, ai-input=yes',
+    `Sitemap: ${SITE_ORIGIN}/sitemap.xml`,
+    '',
+  ];
+
+  await writeTextFile(outputBase, 'robots.txt', lines.join('\n'));
+};
+
+const generateAgentSkillsIndex = async (outputBase) => {
+  const skillPath = '/SKILL.md';
+  const skillHash = await sha256('public/SKILL.md');
+  const index = {
+    $schema: 'https://docs.celestia.org/.well-known/agent-skills/schema.json',
+    skills: [
+      {
+        name: 'celestia',
+        type: 'codex-skill',
+        description: 'Route Celestia requests to the correct repo and apply canonical blob submit/retrieve guidance with docs guardrails.',
+        url: `${SITE_ORIGIN}${skillPath}`,
+        sha256: skillHash,
+      },
+    ],
+  };
+
+  await writeTextFile(outputBase, '.well-known/agent-skills/index.json', `${JSON.stringify(index, null, 2)}\n`);
+};
+
+const generateApiCatalog = async (outputBase) => {
+  const linkset = {
+    linkset: [
+      {
+        anchor: SITE_ORIGIN,
+        'service-desc': [
+          {
+            href: `${SITE_ORIGIN}${LATEST_OPENRPC_SPEC}`,
+            type: 'application/json',
+            title: 'Celestia Node API OpenRPC specification',
+          },
+        ],
+        'service-doc': [
+          {
+            href: `${SITE_ORIGIN}/build/rpc/node-api/`,
+            type: 'text/html',
+            title: 'Celestia Node API documentation',
+          },
+          {
+            href: `${SITE_ORIGIN}/build/rpc/clients/`,
+            type: 'text/html',
+            title: 'Celestia RPC clients',
+          },
+        ],
+        describedby: [
+          {
+            href: `${SITE_ORIGIN}/llms.txt`,
+            type: 'text/plain',
+            title: 'Celestia docs LLM index',
+          },
+          {
+            href: `${SITE_ORIGIN}/llms-full.txt`,
+            type: 'text/plain',
+            title: 'Celestia docs full LLM context',
+          },
+          {
+            href: `${SITE_ORIGIN}/SKILL.md`,
+            type: 'text/markdown',
+            title: 'Celestia agent skill',
+          },
+        ],
+        status: [
+          {
+            href: `${SITE_ORIGIN}/operate/maintenance/troubleshooting/`,
+            type: 'text/html',
+            title: 'Celestia troubleshooting documentation',
+          },
+        ],
+        'source-code': [
+          {
+            href: GITHUB_REPO,
+            type: 'text/html',
+            title: 'Celestia docs repository',
+          },
+        ],
+      },
+    ],
+  };
+
+  await writeTextFile(outputBase, '.well-known/api-catalog', `${JSON.stringify(linkset, null, 2)}\n`);
+};
 
-  console.log(`llms.txt generated (${outputBase}/)`);
-  console.log('✨ LLM-ready markdown generation complete!');
+const main = async () => {
+  // Determine output directory once - use 'out' if it exists (during build), otherwise 'public' (during dev)
+  const outputBase = await fs.access('out').then(() => 'out').catch(() => 'public');
+  const files = (await walkPages('app')).sort();
+
+  // Generate individual markdown files
+  const pages = await generateMarkdownFiles(outputBase, files);
+
+  const sections = buildSections(files);
+  await fs.mkdir(outputBase, { recursive: true });
+  await generateLlmsTxt(outputBase, sections);
+  await generateSectionLlmsTxt(outputBase, sections);
+  await generateLlmsFullTxt(outputBase, pages);
+  await generateSitemap(outputBase, pages);
+  await generateRobotsTxt(outputBase);
+  await generateAgentSkillsIndex(outputBase);
+  await generateApiCatalog(outputBase);
+
+  console.log(`Agent-ready assets generated (${outputBase}/)`);
+  console.log('✨ LLM-ready markdown and discovery asset generation complete!');
 };
 
 main().catch((err) => {

From e367e4cb7d40af9fa9a6ac01d1464c11c75f7759 Mon Sep 17 00:00:00 2001
From: Gabriel Barros <gbbabarros@gmail.com>
Date: Fri, 22 May 2026 10:49:45 -0300
Subject: [PATCH 2/3] Add structured data for software application and FAQ to
 improve SEO

---
 app/layout.tsx           | 58 +++++++++++++++++++++++++++++++++++++++-
 scripts/generate-llms.js | 10 ++++---
 2 files changed, 63 insertions(+), 5 deletions(-)

diff --git a/app/layout.tsx b/app/layout.tsx
index e1e48402576..8603235586f 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -109,7 +109,63 @@ const documentationJsonLd = {
   ],
 };
 
-const jsonLd = [organizationJsonLd, websiteJsonLd, documentationJsonLd];
+const softwareApplicationJsonLd = {
+  "@context": "https://schema.org",
+  "@type": "SoftwareApplication",
+  name: "Celestia Node API",
+  applicationCategory: "DeveloperApplication",
+  operatingSystem: ["Linux", "macOS"],
+  url: `${SITE_ORIGIN}/build/rpc/node-api/`,
+  softwareHelp: `${SITE_ORIGIN}/operate/maintenance/troubleshooting/`,
+  isAccessibleForFree: true,
+  publisher: {
+    "@type": "Organization",
+    name: "Celestia",
+    url: "https://celestia.org",
+  },
+};
+
+const faqJsonLd = {
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  mainEntity: [
+    {
+      "@type": "Question",
+      name: "Where can I troubleshoot Celestia node issues?",
+      acceptedAnswer: {
+        "@type": "Answer",
+        text: "Use the Celestia troubleshooting documentation for common node, sync, network, and operational issues.",
+        url: `${SITE_ORIGIN}/operate/maintenance/troubleshooting/`,
+      },
+    },
+    {
+      "@type": "Question",
+      name: "Where can I find the Celestia Node API reference?",
+      acceptedAnswer: {
+        "@type": "Answer",
+        text: "Use the Celestia Node API reference for RPC methods and the OpenRPC specification for machine-readable API details.",
+        url: `${SITE_ORIGIN}/build/rpc/node-api/`,
+      },
+    },
+    {
+      "@type": "Question",
+      name: "Where can I learn how to run a Celestia light node?",
+      acceptedAnswer: {
+        "@type": "Answer",
+        text: "Start with the light node quickstart guide, then use the troubleshooting page if setup, sync, or connectivity issues appear.",
+        url: `${SITE_ORIGIN}/operate/data-availability/light-node/quickstart/`,
+      },
+    },
+  ],
+};
+
+const jsonLd = [
+  organizationJsonLd,
+  websiteJsonLd,
+  documentationJsonLd,
+  softwareApplicationJsonLd,
+  faqJsonLd,
+];
 
 const banner = (
   <Banner storageKey="some-key">Welcome to our new docs! 🎉</Banner>
diff --git a/scripts/generate-llms.js b/scripts/generate-llms.js
index a258cf882dc..d6aa6307b78 100644
--- a/scripts/generate-llms.js
+++ b/scripts/generate-llms.js
@@ -419,21 +419,23 @@ const generateRobotsTxt = async (outputBase) => {
 };
 
 const generateAgentSkillsIndex = async (outputBase) => {
-  const skillPath = '/SKILL.md';
+  const skillPath = '/.well-known/agent-skills/celestia/SKILL.md';
   const skillHash = await sha256('public/SKILL.md');
   const index = {
-    $schema: 'https://docs.celestia.org/.well-known/agent-skills/schema.json',
+    $schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
     skills: [
       {
         name: 'celestia',
-        type: 'codex-skill',
+        type: 'skill-md',
         description: 'Route Celestia requests to the correct repo and apply canonical blob submit/retrieve guidance with docs guardrails.',
         url: `${SITE_ORIGIN}${skillPath}`,
-        sha256: skillHash,
+        digest: `sha256:${skillHash}`,
       },
     ],
   };
 
+  await fs.mkdir(path.join(outputBase, '.well-known/agent-skills/celestia'), { recursive: true });
+  await fs.copyFile('public/SKILL.md', path.join(outputBase, '.well-known/agent-skills/celestia/SKILL.md'));
   await writeTextFile(outputBase, '.well-known/agent-skills/index.json', `${JSON.stringify(index, null, 2)}\n`);
 };
 

From 627445c554f34b77095ce27c692dc635f13b6658 Mon Sep 17 00:00:00 2001
From: Gabriel Barros <gbbabarros@gmail.com>
Date: Fri, 22 May 2026 14:10:49 -0300
Subject: [PATCH 3/3] Address AI readiness PR review feedback

---
 app/layout.tsx           |  9 ---------
 scripts/generate-llms.js | 13 +++++++++++--
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/app/layout.tsx b/app/layout.tsx
index 8603235586f..e5da0a3c200 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -33,12 +33,8 @@ export const metadata = {
     template: "%s - Celestia Documentation",
   },
   description: SITE_DESCRIPTION,
-  alternates: {
-    canonical: "/",
-  },
   openGraph: {
     type: "website",
-    url: SITE_ORIGIN,
     siteName: "Celestia Documentation",
     title: "Celestia Documentation",
     description: SITE_DESCRIPTION,
@@ -223,11 +219,6 @@ export default async function RootLayout({
           href={withBasePath("/favicons/favicon-16x16.png")}
         />
         <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <meta property="og:title" content="Celestia Documentation" />
-        <meta
-          property="og:description"
-          content={SITE_DESCRIPTION}
-        />
         <link rel="alternate" type="text/plain" href={withBasePath("/llms.txt")} />
         <link
           rel="alternate"
diff --git a/scripts/generate-llms.js b/scripts/generate-llms.js
index d6aa6307b78..f50e8da87f2 100644
--- a/scripts/generate-llms.js
+++ b/scripts/generate-llms.js
@@ -249,7 +249,12 @@ const buildSections = (files) => {
   for (const file of files) {
     const rel = toPosixPath(file).replace(/^app\//, '');
     const parts = rel.split('/');
-    if (parts.length < 2) continue; // skip unexpected roots
+    if (parts.length < 2) {
+      const label = rel === 'page.mdx' ? 'Home' : titleize(rel.replace(/\.mdx$/, ''));
+      if (!grouped.has('Overview')) grouped.set('Overview', []);
+      grouped.get('Overview').push({ file, label });
+      continue;
+    }
 
     const [top, second, ...rest] = parts;
     // Section title: "Top" or "Top: Second"
@@ -265,7 +270,11 @@ const buildSections = (files) => {
   }
 
   // Sort sections and items for stability
-  const sortedSections = [...grouped.entries()].sort(([a], [b]) => a.localeCompare(b));
+  const sortedSections = [...grouped.entries()].sort(([a], [b]) => {
+    if (a === 'Overview') return -1;
+    if (b === 'Overview') return 1;
+    return a.localeCompare(b);
+  });
   return sortedSections.map(([title, items]) => ({
     title,
     items: items.sort((a, b) => a.file.localeCompare(b.file)),