#!/usr/bin/env node /** * Generate llms.txt artifacts for the Telnyx developer docs. * * Usage: node scripts/docs/generate-llms-txt.js * * Reads docs.json from the repo root, walks the navigation tree, * and produces: * * Committed to the repo (served by Mintlify, which only serves these * exact filenames — any other root/public .txt 404s): * llms.txt – root index (<50K) linking every per-section and * per-subsection file; overrides Mintlify's auto * llms.txt * llms-full.txt – <200K map: auth + quickstarts + links to the * per-area full-content files (overrides auto version) * * Also committed — regenerated on every run as minimal Mintlify page * registrations whose routes redirect to the raw contextual assets: * docs/development/llms/-llms-txt/index.mdx * docs/development/llms/-llms-full-txt/index.mdx * docs/development/llms/-_{-llms-txt/index.mdx
* docs/development/llms/-_{-llms-full-txt/index.mdx
* docs/development/llms/code-examples/index.mdx – hidden page carrying the
* code-examples snippet, linked from llms.txt
* docs.json – a "For AI Agents" group inside every subsection
* pointing at the two landing pages (idempotent)
*
* Temporary build artifacts are written to llms-out/ and copied into the
* contextual raw assets under public/llms/. llms-out/ itself remains gitignored:
* llms-out/.txt – per-section index (pages + endpoints)
* llms-out/-full.txt – per-section full page content
* llms-out//_{.txt – per-subsection index
* llms-out//_{-full.txt – per-subsection full page content
*
* All links inside llms-out/ files are absolute so copied static assets do
* not depend on their eventual directory depth.
*
* Follows the llms.txt convention: https://llmstxt.org/
*/

const fs = require("fs");
const path = require("path");
const yaml = require("js-yaml");

const REPO_ROOT = path.resolve(__dirname, "../..");
const DOCS_JSON_PATH = path.join(REPO_ROOT, "docs.json");
const PUBLIC_DIR = path.join(REPO_ROOT, "public");
const LLMS_OUT_DIR = path.join(REPO_ROOT, "llms-out");
const RAW_LLMS_DIR = path.join(PUBLIC_DIR, "llms");
// Generated sidebar landing pages live here (wiped + rewritten every run).
const LANDING_DIR = path.join(REPO_ROOT, "docs", "development", "llms");
const BASE_URL = "https://developers.telnyx.com";
const CONSOLIDATED_OPENAPI_SPEC_URL =
"https://raw.githubusercontent.com/team-telnyx/openapi/master/openapi/spec3.json";

// Slugify a title/tag the same way Mintlify renders OpenAPI operation routes:
// apostrophes, slashes, and parentheses are stripped (not hyphenated);
// underscores are preserved as-is; everything else collapses to single hyphens.
function slugifyOpenApi(s) {
return (s || "")
.toLowerCase()
.replace(/['/()]/g, "")
.replace(/[^a-z0-9_]+/g, "-")
.replace(/^-|-$/g, "");
}

// ---------------------------------------------------------------------------
// Tabs: slugs and descriptions for the per-section files
// ---------------------------------------------------------------------------

const TAB_SLUGS = {
"AI": "ai",
"Agent SDK": "ai-agent-sdk-beta",
"Agent Tools": "agent-tools",
"AI": "ai",
"Compute": "compute",
"Storage": "storage",
"Calling": "calling",
"Voice": "voice",
"Messaging": "messaging",
"Numbers": "numbers",
"Wireless": "wireless",
"Fundamentals": "fundamentals",
};

// Overview is the product landscape landing page, not a product corpus. Every
// other published tab must have an explicit slug so navigation changes fail
// closed instead of silently disappearing from the machine-readable indexes.
const LLMS_EXCLUDED_TABS = new Set(["Overview"]);

function deriveTabOrder(docsJson) {
const tabs = navigationTabs(docsJson);
const order = [];
for (const tab of tabs) {
const tabName = tab.tab;
if (!tabName || LLMS_EXCLUDED_TABS.has(tabName)) continue;
if (!TAB_SLUGS[tabName]) {
throw new Error(`Missing LLMS slug for navigation tab "${tabName}"`);
}
order.push(tabName);
}
return order;
}

const TAB_DESCRIPTIONS = {
"AI": "Inference, embedding, AI assistants, missions, and LiveKit integrations",
"Agent SDK":
"Build and run stateful AI agents with scheduling, message history, SQL, and WebSockets",
"Agent Tools":
"Hosted tools for AI agents: web search, deep research, AI Search, memory, browser, payment, and meeting",
"AI": "Inference, embedding, AI assistants, missions, and LiveKit integrations",
"Calling":
"TeXML, SIP trunking, UAC connections, WebRTC, and trusted calling",
"Voice": "Voice API, speech-to-text, text-to-speech, and voice design",
"Messaging":
"SMS, MMS, RCS, WhatsApp, short codes, 10DLC compliance, and messaging profiles",
"Numbers":
"Phone number search and ordering, porting, regulatory requirements, and identity",
"Compute": "Edge compute functions, runtime bindings, stateful actors, and private networking",
"Storage": "S3-compatible cloud storage with buckets, SDKs, and migration from AWS",
"Wireless": "SIMs, eSIMs, IoT data plans, VoLTE, and wireless messaging",
"Fundamentals":
"Account setup, authentication, SDKs, developer tools, and supporting platform APIs",
};

// ---------------------------------------------------------------------------
// Navigation shape adapter — legacy tabs view over the products division
// ---------------------------------------------------------------------------
// docs.json uses navigation.products (Cloudflare-style suites: a directory
// Home plus one mini-site per suite). This adapter presents the products
// division as main's tab families so every walker below works on either
// shape, and every published llms slug in TAB_SLUGS stays stable:
//
// product "Home" → tab "Fundamentals" (account setup, auth, SDKs, CLI,
// developer tools, and the supporting/other platform APIs)
// "Networking" → family "Compute" (split out of Compute in the nav;
// compute-network-* routes never move)
// every other suite → the same-named family
//
// A suite missing from TAB_SLUGS after this mapping makes generation fail
// closed in deriveTabOrder — add the family there or map the suite here.
const PRODUCT_TO_TAB = {
"Other APIs": "Fundamentals",
"Home": "Fundamentals",
"Networking": "Compute",
};

const HOME_PRODUCT = "Home";

function productFamilyForNestedTab(productName, nestedTabName) {
return PRODUCT_TO_TAB[productName] || productName;
}

// Menu-item view over a nested product tab. Only the keys the walkers read
// (item/groups/pages) — copying `tab` or `icon` through would corrupt the
// walkers' navigation context.
function menuItemView(nestedTab) {
const view = { item: nestedTab.tab };
if (nestedTab.groups) view.groups = nestedTab.groups;
if (nestedTab.pages) view.pages = nestedTab.pages;
return view;
}

// Read-only legacy view of the navigation. Group and page objects are shared
// with docs.json, not cloned — walkers must not mutate them (the sidebar
// updater walks the real shape itself for exactly that reason).
function navigationTabs(docsJson) {
const navigation = docsJson.navigation || {};
if (navigation.tabs) return navigation.tabs;

const legacyTabs = new Map();
const legacyMenuTab = (name) => {
if (!legacyTabs.has(name)) legacyTabs.set(name, { tab: name, menu: [] });
return legacyTabs.get(name);
};

for (const product of navigation.products || []) {
if (product.product === HOME_PRODUCT) {
// Home's groups are the head of the flat Fundamentals family.
const family = PRODUCT_TO_TAB[HOME_PRODUCT];
const entry = legacyTabs.get(family) || { tab: family, groups: [] };
entry.groups = [...(product.groups || []), ...entry.groups];
legacyTabs.set(family, entry);
continue;
}
if (product.product === "Other APIs") {
// Renders as its own mini-site, but its corpus stays the Fundamentals
// family's "Other APIs" subsection — the same nested shape it had as
// a Home group, so the Fundamentals special cases keep applying.
const family = PRODUCT_TO_TAB[HOME_PRODUCT];
const entry = legacyTabs.get(family) || { tab: family, groups: [] };
for (const nestedTab of product.tabs || []) {
entry.groups.push({ group: nestedTab.tab, pages: nestedTab.groups || [] });
}
legacyTabs.set(family, entry);
continue;
}
for (const nestedTab of product.tabs || []) {
const family = productFamilyForNestedTab(product.product, nestedTab.tab);
legacyMenuTab(family).menu.push(menuItemView(nestedTab));
}
}
return [...legacyTabs.values()];
}

// ---------------------------------------------------------------------------
// Agent-facing sections shared by the root llms.txt and llms-full.txt
// ---------------------------------------------------------------------------

const USE_CASES_MD = `## Use cases

- Voice AI agents and IVR: real-time voice assistants combining carrier-grade calling with STT, TTS, and LLM inference on one platform
- Programmatic messaging: SMS, MMS, RCS, and WhatsApp for OTP, alerts, and campaigns
- Phone numbers: search, order, port, and configure numbers programmatically across global markets
- IoT connectivity: SIMs and eSIMs with per-MB data and private wireless
- AI inference: OpenAI-compatible chat completions and embeddings hosted on Telnyx GPUs
- Networking and storage: private IP networking and S3-compatible cloud storage

`;

const CONSTRAINTS_MD = `## Constraints

- REST authentication: use a server-side Bearer API key for an integration operating its own account; delegated OAuth and other product protocols have separate authentication requirements — see https://developers.telnyx.com/auth.md
- Base URL: https://api.telnyx.com/v2 (REST, JSON request/response)
- Rate limits are enforced per endpoint — see APIs fundamentals under the Fundamentals section
- US A2P messaging requires 10DLC registration; some number purchases require country-specific regulatory documents
- When a product documents Ed25519 webhook signing, verify the signature before trusting the payload; follow the selected product's validation and acknowledgment contract

`;

const FOR_AGENTS_MD = `## For AI agents

- When to use Telnyx: tasks requiring programmable voice or calls, messaging, phone numbers, wireless connectivity, AI inference, or low-latency media
- Agent-readable documentation map: ${BASE_URL}/docs/development/agent-readable-documentation.md
- Clean page Markdown: append \`.md\` to a developers.telnyx.com documentation URL; interactive browser components are excluded and replaced with text fallbacks or canonical data sources
- REST: use the consolidated OpenAPI spec linked below with header \`Authorization: Bearer \`
- Structured API errors: ${BASE_URL}/data/api-errors.json · webhook request payloads and publication selectors: ${BASE_URL}/data/webhook-events.json
- MCP (API actions): connect to https://api.telnyx.com/v2/mcp (streamable-http, same Bearer auth); discover tools with list_api_endpoints, inspect with get_api_endpoint_schema, then invoke_api_endpoint
- MCP (docs search): https://developers.telnyx.com/mcp (no auth)
- Credential walkthrough (auth.md convention): https://developers.telnyx.com/auth.md
- API-key signup: obtain account-owner authorization, then follow the signup runbook (documentation, not an API endpoint) at https://telnyx.com/agent-signup.md. Complete email verification, use the temporary session token to create the API key, and store the key in a secret manager; do not log credentials. Existing accounts can manage keys interactively at https://portal.telnyx.com/#/app/api-keys. Verify with a read-only GET https://api.telnyx.com/v2/phone_numbers using \`Authorization: Bearer \`; revoke or rotate keys through the portal.
- Agent platform configs (AGENTS.md, .cursorrules, .claude/, .windsurf/): https://github.com/team-telnyx/ai
- Machine-readable capabilities: https://telnyx.com/ai/capabilities.json · Pricing: https://telnyx.com/pricing.md · Agent fast path: https://telnyx.com/agents/start
- Differentiation vs alternatives: https://developers.telnyx.com/compare

`;

const RELIABILITY_MD = `## Reliability & Status

- Status page: https://status.telnyx.com — live platform status and incident history (incident.io-powered)
- Machine-readable status (Statuspage-compatible JSON API): current status and active incidents at https://status.telnyx.com/api/v2/summary.json · recent incident history at https://status.telnyx.com/api/v2/incidents.json · per-component status at https://status.telnyx.com/api/v2/components.json
- Incident feeds: RSS at https://status.telnyx.com/history.rss · Atom at https://status.telnyx.com/history.atom
- SLA, machine-readable: https://telnyx.com/ai/sla.json (99.99% uptime guarantee, RPO/RTO, credit tiers) · Resilience details: https://telnyx.com/ai/resilience.md
- Building for reliability: [rate limiting](${BASE_URL}/docs/development/api-fundamentals/reliability/rate-limiting.md), [command retries](${BASE_URL}/docs/development/api-fundamentals/reliability/command-retries.md), [API error codes](${BASE_URL}/docs/development/api-fundamentals/api-errors.md), [webhook signatures and retries](${BASE_URL}/docs/development/api-fundamentals/webhooks/receiving-webhooks.md)

`;

const WHY_TELNYX_MD = `## Why Telnyx (vs alternatives)

Unlike reseller CPaaS platforms (e.g. Twilio or Vonage), Telnyx owns and operates its global carrier network and runs AI inference on its own GPU infrastructure — one platform and one bill for voice, messaging, numbers, wireless, and AI, with usage-based rates published openly at https://telnyx.com/pricing.md. See https://telnyx.com/why-telnyx, the comparison page at https://developers.telnyx.com/compare.md, and the Twilio migration guide in the Fundamentals section.

`;

const AUTH_QUICKSTART_MD = `## Authentication

Every API request authenticates with a Bearer API key:

\`\`\`bash
curl https://api.telnyx.com/v2/available_phone_numbers \\
-H "Authorization: Bearer $TELNYX_API_KEY"
\`\`\`

Create a key in the Mission Control Portal (https://portal.telnyx.com) or programmatically via the agent signup flow (https://telnyx.com/agent-signup.md).

## Quickstart examples

Send an SMS:

\`\`\`bash
curl -X POST https://api.telnyx.com/v2/messages \\
-H "Authorization: Bearer $TELNYX_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"from": "+13125550100", "to": "+13125550101", "text": "Hello from Telnyx"}'
\`\`\`

Chat completion (OpenAI-compatible):

\`\`\`bash
curl -X POST https://api.telnyx.com/v2/ai/chat/completions \\
-H "Authorization: Bearer $TELNYX_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"model": "meta-llama/Llama-3.3-70B-Instruct", "messages": [{"role": "user", "content": "Hello"}]}'
\`\`\`

`;

function tabIndexUrl(tabName) {
return `${BASE_URL}/docs/development/llms/${TAB_SLUGS[tabName]}-llms-txt`;
}

function tabFullUrl(tabName) {
return `${BASE_URL}/docs/development/llms/${TAB_SLUGS[tabName]}-llms-full-txt`;
}

// Groups to skip (not real content groups)
const SKIP_GROUPS = new Set([
"🤖 For AI Agents",
"For AI Agents",
"Migration Guides",
"Glossary",
]);

// Keep docs-only MCP Apps pages out of developer-docs llms indexes so
// scanners don't treat the docs MCP surface as promising app UI resources.
// Product MCP Apps remain discoverable from the product MCP server itself.
const LLMS_INDEX_SKIP_REFS = new Set(["docs/development/mcp/mcp-apps/index"]);

// ---------------------------------------------------------------------------
// Subsections (the menu items / top-level groups inside each tab)
// ---------------------------------------------------------------------------

// Keep generated URLs short where a literal slugification would be unwieldy.
const SUBSECTION_SLUG_OVERRIDES = {
"LiveKit on Telnyx (Beta)": "livekit",
"SQL (Beta)": "sql",
};

function subsectionSlug(subName) {
return SUBSECTION_SLUG_OVERRIDES[subName] || slugifyOpenApi(subName);
}

function llmsPageUrl(ref) {
return `${BASE_URL}/${ref.replace(/\/index$/, "")}`;
}

function subIndexUrl(tabName, subName) {
return llmsPageUrl(landingPageRefs(tabName, subName)[0]);
}

function subFullUrl(tabName, subName) {
return llmsPageUrl(landingPageRefs(tabName, subName)[1]);
}

// Composite key for per-subsection maps.
function subKey(tabName, subName) {
return `${tabName} ${subName}`;
}

// Tab → ordered list of subsection names, straight from docs.json.
// Derived dynamically so new menu items / groups are picked up with no
// code change (a hardcoded map here went stale within weeks in May).
function deriveSubsections(docsJson) {
const map = new Map();
for (const tab of navigationTabs(docsJson)) {
const subs = [];
if (tab.menu) {
for (const m of tab.menu) {
const n = m.item;
if (!n || !n.trim() || SKIP_GROUPS.has(n)) continue;
subs.push(n);
}
} else if (tab.groups) {
for (const g of tab.groups) {
const n = g.group;
if (!n || !n.trim() || SKIP_GROUPS.has(n)) continue;
subs.push(n);
}
}
map.set(tab.tab, subs);
}
return map;
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

function readDocsJson() {
const raw = fs.readFileSync(DOCS_JSON_PATH, "utf8");
return JSON.parse(raw);
}

function parseFrontmatter(content) {
const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
if (!match) return null;
const fm = {};
const lines = match[1].split(/\r?\n/);
for (const line of lines) {
const m = line.match(/^(\w[\w-]*):\s*(.*)$/);
if (m) {
let val = m[2].trim();
if (
(val.startsWith('"') && val.endsWith('"')) ||
(val.startsWith("'") && val.endsWith("'"))
) {
val = val.slice(1, -1);
}
fm[m[1]] = val;
}
}
return fm;
}

function stripFrontmatter(content) {
return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
}

function stripMdxComponents(content) {
const lines = content.split("\n");
const result = [];
let inCodeBlock = false;

for (const line of lines) {
if (line.trimStart().startsWith("```")) {
inCodeBlock = !inCodeBlock;
result.push(line);
continue;
}
if (inCodeBlock) {
result.push(line);
continue;
}

// Skip self-closing JSX tags
if (/^<\w+[^>]*\/>\s*$/.test(line.trim())) {
continue;
}

// Skip opening JSX tags on their own line
if (/^<\w+[^>]*>\s*$/.test(line.trim())) {
continue;
}

// Skip closing JSX tags
if (/^<\/\w+[^>]*>\s*$/.test(line.trim())) {
continue;
}

// Skip import statements
if (/^import\s/.test(line.trim())) {
continue;
}

// Skip export statements
if (/^export\s/.test(line.trim())) {
continue;
}

result.push(line);
}

let output = result.join("\n");

// Code is content, not markup. Mask fenced blocks and inline spans before the
// JSX strippers run, or they eat angle-bracket placeholders out of commands and
// manifest keys — `env.` becomes `env.` and
// `telnyx-edge auth api-key set ` loses its argument.
const masked = [];
const mask = (match) => `\u0000CODE${masked.push(match) - 1}\u0000`;

// Fenced blocks first, so a comment or tag shown as an example survives.
output = output.replace(/```[\s\S]*?```/g, mask);

// MDX comments never render on the page, so they must not reach the text output.
output = output.replace(/\{\/\*[\s\S]*?\*\/\}/g, "");

// Inline code spans, which do not run across lines.
output = output.replace(/(`+)[^`\n]+?\1/g, mask);

// Remove self-closing JSX tags inline
output = output.replace(/<\w+[^>]*\/>/g, "");

// Remove opening/closing tags but keep content between them
output = output.replace(/<\/?\w+[^>]*>/g, "");

output = output.replace(/\u0000CODE(\d+)\u0000/g, (_, i) => masked[Number(i)]);

// Collapse multiple blank lines to at most two
output = output.replace(/\n{3,}/g, "\n\n");

return output.trim();
}

function pageRefToUrl(ref) {
let slug = ref;
if (slug.endsWith("/index")) {
slug = slug.slice(0, -6);
}
return `${BASE_URL}/${slug}`;
}

/**
* Append .md to same-origin URLs so agents get markdown instead of HTML.
*/
function toMdUrl(url) {
if (url && url.startsWith(BASE_URL)) {
return url + ".md";
}
return url;
}

function shouldSkip(ref) {
if (typeof ref !== "string") return false;
if (ref.startsWith("https://")) return true;
if (/^(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD|TRACE)\s\//.test(ref)) return true;
return false;
}

function resolveMdxPath(ref) {
const p = path.join(REPO_ROOT, `${ref}.mdx`);
if (fs.existsSync(p)) return p;
return null;
}

// Truncate a frontmatter description for index bullets.
function shortDescription(s, max = 200) {
if (!s) return "";
const oneLine = s.split("\n")[0].trim();
if (oneLine.length <= max) return oneLine;
return oneLine.slice(0, max - 1).trimEnd() + "…";
}

// ---------------------------------------------------------------------------
// Navigation tree walker
// ---------------------------------------------------------------------------

function walkNavigation(docsJson) {
const tabs = navigationTabs(docsJson);
const allPages = [];

for (const tab of tabs) {
const tabName = tab.tab;

if (tab.menu) {
for (const menuItem of tab.menu) {
const itemName = menuItem.item;
if (SKIP_GROUPS.has(itemName)) continue;

for (const group of menuItem.groups || []) {
walkPages(group.pages || [], tabName, [itemName, group.group], allPages);
}
if (menuItem.pages) {
walkPages(menuItem.pages, tabName, [itemName], allPages);
}
}
} else if (tab.groups) {
for (const group of tab.groups) {
const groupName = group.group;
const isFundamentalsAiAgentsGroup =
(tabName === "Fundamentals" || tabName === "Development") &&
(groupName === "🤖 For AI Agents" || groupName === "For AI Agents");
if (SKIP_GROUPS.has(groupName) && !isFundamentalsAiAgentsGroup) continue;
if (groupName.trim() === "") continue;

walkPages(group.pages || [], tabName, [groupName], allPages);
}
}
}

return allPages;
}

function walkPages(entries, tabName, groupPath, pages) {
for (const entry of entries) {
if (typeof entry === "string") {
if (shouldSkip(entry)) continue;
if (LLMS_INDEX_SKIP_REFS.has(entry)) continue;
// Skip llms-txt/llms-txt-full pages
if (entry.includes("llms-txt") || entry.includes("llms-full-txt") || entry.includes("llms/")) continue;
// Skip agent-llms pages
if (entry.includes("agent-llms")) continue;
const mdxPath = resolveMdxPath(entry);
if (!mdxPath) continue;
const url = pageRefToUrl(entry);
const rawContent = fs.readFileSync(mdxPath, "utf8");
const fm = parseFrontmatter(rawContent);
const title =
fm?.sidebarTitle || fm?.title || path.basename(entry, ".mdx");
const description = fm?.description || "";
const content = stripMdxComponents(stripFrontmatter(rawContent));

pages.push({
tab: tabName,
groupPath,
pageRef: entry,
mdxPath,
url,
title,
description,
content,
});
} else if (entry.group && entry.pages) {
walkPages(entry.pages, tabName, [...groupPath, entry.group], pages);
} else if (entry.groups) {
for (const g of entry.groups) {
walkPages(g.pages || [], tabName, groupPath, pages);
}
}
}
}

// Organize walked pages by tab → first-level group, preserving nav order.
function groupPagesByTab(pages) {
const tabGroups = {};
for (const page of pages) {
const tab = page.tab;
const group = page.groupPath[0] || "(ungrouped)";
if (!tabGroups[tab]) tabGroups[tab] = {};
if (!tabGroups[tab][group]) tabGroups[tab][group] = [];
tabGroups[tab][group].push(page);
}
return tabGroups;
}

// Organize pages by tab+subsection → inner group, preserving nav order.
// groupPath[0] is always the subsection (menu item or top-level group);
// groupPath[1], when present, is the heading group inside it.
function groupPagesBySubsection(pages) {
const map = new Map();
for (const page of pages) {
const sub = page.groupPath[0] || "(ungrouped)";
const inner = page.groupPath[1] || "";
const key = subKey(page.tab, sub);
if (!map.has(key)) map.set(key, new Map());
const innerMap = map.get(key);
if (!innerMap.has(inner)) innerMap.set(inner, []);
innerMap.get(inner).push(page);
}
return map;
}

// ---------------------------------------------------------------------------
// Collect OpenAPI specs from docs.json
// ---------------------------------------------------------------------------

// Turn a spec ref like "call-control-commands/dial.yml" or a full S3 URL
// ending in "ai/inference.yml" into a human-friendly label
// ("Call Control Commands — Dial"). Falls back to nav-tree context if the
// immediate label is just "API Reference".
function deriveSpecName(ref, ctx) {
if (ctx.group && ctx.group !== "API Reference") return ctx.group;
const lastTwo = ref.replace(/\.(ya?ml|json)$/i, "").split("/").slice(-2);
const ACRONYMS = new Set(["ai", "api", "sip", "stt", "tts", "sms", "mms", "rcs", "uac", "ip", "url", "id"]);
const toTitle = (s) =>
s
.replace(/[-_]+/g, " ")
.split(" ")
.filter(Boolean)
.map((w) => (ACRONYMS.has(w) ? w.toUpperCase() : w[0].toUpperCase() + w.slice(1)))
.join(" ");
if (lastTwo.length === 2) return `${toTitle(lastTwo[0])} — ${toTitle(lastTwo[1])}`;
return toTitle(lastTwo[0] || "API");
}

// Walk the navigation tree and collect both legacy `openapi:` objects and
// Mintlify file-qualified selectors. Each tab is visited one subsection at a
// time so every spec remains attributed to the navigation context that owns it.
function collectOpenApiSpecs(docsJson) {
const specs = [];
const specsByContext = new Map();

const collectOperationRefs = (pages, refs = []) => {
if (!pages) return refs;
if (Array.isArray(pages)) {
for (const page of pages) collectOperationRefs(page, refs);
} else if (
typeof pages === "string" &&
/^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE)\s+\//.test(pages)
) {
if (!refs.includes(pages)) refs.push(pages);
} else if (typeof pages === "object") {
collectOperationRefs(pages.pages, refs);
collectOperationRefs(pages.groups, refs);
}
return refs;
};

const addSpec = (specUrl, operationRefs, ctx) => {
const tab = ctx.tab || "API";
const subsection = ctx.subsection || null;
const contextKey = JSON.stringify([specUrl, tab, subsection]);
const existing = specsByContext.get(contextKey);
if (existing) {
if (existing.allOperations || operationRefs.length === 0) {
existing.allOperations = true;
existing.spec.operationRefs = [];
} else {
for (const ref of operationRefs) {
if (!existing.spec.operationRefs.includes(ref)) existing.spec.operationRefs.push(ref);
}
}
return;
}

const spec = {
name: deriveSpecName(specUrl, ctx),
url: specUrl,
tab,
subsection,
operationRefs: [...operationRefs],
};
specs.push(spec);
specsByContext.set(contextKey, {
spec,
allOperations: operationRefs.length === 0,
});
};

const parseQualifiedSelector = (value) => {
const match = value.match(
/^(.+\.(?:ya?ml|json))\s+((?:(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE)\s+\/.+)|(?:webhook\s+.+))$/i
);
if (!match) return null;
let selector = match[2].trim();
const rest = selector.match(/^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE)\s+(\/.+)$/i);
selector = rest
? `${rest[1].toUpperCase()} ${rest[2]}`
: `webhook ${selector.replace(/^webhook\s+/i, "")}`;
return { specUrl: match[1], selector };
};

const visit = (node, ctx) => {
if (!node) return;
if (typeof node === "string") {
const qualified = parseQualifiedSelector(node);
if (qualified) addSpec(qualified.specUrl, [qualified.selector], ctx);
return;
}
if (typeof node !== "object") return;

if (Array.isArray(node)) {
for (const child of node) visit(child, ctx);
return;
}

// Update context as we descend (subsection is fixed at the seed level)
const nextCtx = { ...ctx };
if (node.tab) nextCtx.tab = node.tab;
if (node.group && !SKIP_GROUPS.has(node.group)) nextCtx.group = node.group;
if (node.item && !SKIP_GROUPS.has(node.item)) nextCtx.group = node.item;

// Bail out of skipped subtrees entirely
if ((node.group && SKIP_GROUPS.has(node.group)) || (node.item && SKIP_GROUPS.has(node.item))) {
return;
}

// Preserve the legacy object form during direct-source migration.
if (typeof node.openapi === "string" && /\.(ya?ml|json)$/i.test(node.openapi)) {
addSpec(node.openapi, collectOperationRefs(node.pages), nextCtx);
}

for (const value of Object.values(node)) visit(value, nextCtx);
};

for (const tab of navigationTabs(docsJson)) {
const tabName = tab.tab;
if (tab.menu) {
for (const m of tab.menu) {
if (m.item && SKIP_GROUPS.has(m.item)) continue;
visit(m, { tab: tabName, subsection: m.item || null });
}
} else if (tab.groups) {
for (const g of tab.groups) {
if (g.group && SKIP_GROUPS.has(g.group)) continue;
visit(g, { tab: tabName, subsection: g.group || null });
}
} else {
visit(tab, { tab: tabName, subsection: null });
}
}
return specs;
}

// ---------------------------------------------------------------------------
// Expand OpenAPI specs into per-operation entries
// ---------------------------------------------------------------------------

const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options", "trace"];

async function loadSpec(ref) {
// Local repo paths (e.g. "openapi/voice-clones.yml") vs remote URLs.
if (ref.startsWith("https://") || ref.startsWith("http://")) {
const res = await fetch(ref);
if (!res.ok) throw new Error(`HTTP ${res.status} for ${ref}`);
return yaml.load(await res.text());
}
const localPath = path.isAbsolute(ref) ? ref : path.join(REPO_ROOT, ref);
return yaml.load(fs.readFileSync(localPath, "utf8"));
}

function firstLine(s) {
if (!s) return "";
return s.split("\n")[0].trim();
}

function collectOperationsFromSpec(doc, sourceUrl, fallbackTag = null) {
const operations = [];
const pushOp = (op, method, operationPath, selectorRef = null) => {
if (!op || !op.summary) return;
// Mintlify derives the published URL from the operation's own tags:
// tagged operations live at /api-reference//, untagged ones
// at /api-reference/ with no tag segment. The nav-group fallback
// tag is only for grouping within our generated files — putting it in
// the URL links pages that were never published (the untagged invoice
// operations 404ed at /api-reference/invoices/... this way).
const ownTag = op.tags?.[0] || null;
const rawTag = ownTag || fallbackTag;
if (!rawTag) return;
const tagSlug = slugifyOpenApi(rawTag);
const opSlug = slugifyOpenApi(op.summary);
if (!tagSlug || !opSlug) return;
operations.push({
tag: rawTag,
tagSlug,
operationId: op.operationId || "",
title: op.summary,
description: firstLine(op.description),
url: ownTag ? `/api-reference/${tagSlug}/${opSlug}` : `/api-reference/${opSlug}`,
sourceSpec: sourceUrl,
operationRef: `${method.toUpperCase()} ${operationPath}`,
selectorRef: selectorRef || `${method.toUpperCase()} ${operationPath}`,
});
};

for (const [operationPath, methods] of Object.entries(doc.paths || {})) {
for (const m of HTTP_METHODS) pushOp(methods?.[m], m, operationPath);
}
// Mintlify selects OpenAPI 3.1 webhooks by the webhook map key.
for (const [operationPath, methods] of Object.entries(doc.webhooks || {})) {
for (const m of HTTP_METHODS) {
pushOp(methods?.[m], m, operationPath, `webhook ${operationPath}`);
}
}
return operations;
}

function operationsForSpec(doc, spec) {
const operations = collectOperationsFromSpec(doc, spec.url, spec.name);
const selectors = spec.operationRefs || [];
if (selectors.length === 0) return operations;

return selectors.map((selector) => {
const matches = operations.filter((op) => op.selectorRef === selector);
if (matches.length !== 1) {
throw new Error(
`Selector ${selector} resolved to ${matches.length} operations in ${spec.url}`
);
}
return matches[0];
});
}

/**
* Load every spec once and return:
* allOps – globally deduped operations (for the API Reference shards)
* opsByTab – tab name → operations from that tab's specs, deduped within
* the tab (a shared spec like Callbacks may appear under
* several tabs; each per-section file stays self-contained)
* opsBySub – subKey(tab, subsection) → operations from that subsection's
* specs, deduped within the subsection
*/
async function expandOpenApiOperations(openApiSpecs) {
const allOps = [];
const seenGlobal = new Set();
const opsByTab = new Map();
const seenByTab = new Map();
const opsBySub = new Map();
const seenBySub = new Map();
const loadedSpecs = new Map();

for (const spec of openApiSpecs) {
let doc;
try {
if (!loadedSpecs.has(spec.url)) loadedSpecs.set(spec.url, await loadSpec(spec.url));
doc = loadedSpecs.get(spec.url);
} catch (e) {
throw new Error(`Failed to load ${spec.url}: ${e.message}`, { cause: e });
}
for (const op of operationsForSpec(doc, spec)) {
if (!seenGlobal.has(op.url)) {
seenGlobal.add(op.url);
allOps.push(op);
}
const tab = spec.tab;
if (!opsByTab.has(tab)) {
opsByTab.set(tab, []);
seenByTab.set(tab, new Set());
}
if (!seenByTab.get(tab).has(op.url)) {
seenByTab.get(tab).add(op.url);
opsByTab.get(tab).push(op);
}
if (spec.subsection) {
const key = subKey(spec.tab, spec.subsection);
if (!opsBySub.has(key)) {
opsBySub.set(key, []);
seenBySub.set(key, new Set());
}
if (!seenBySub.get(key).has(op.url)) {
seenBySub.get(key).add(op.url);
opsBySub.get(key).push(op);
}
}
}
}
return { allOps, opsByTab, opsBySub };
}

// Group a list of operations by their first tag, preserving order.
function groupOpsByTag(ops) {
const byTag = new Map();
for (const op of ops) {
if (!byTag.has(op.tag)) byTag.set(op.tag, []);
byTag.get(op.tag).push(op);
}
return byTag;
}

// ---------------------------------------------------------------------------
// Output generation — root llms.txt (nested index, committed to repo)
// ---------------------------------------------------------------------------

function generateRootLlmsIndex(docsJson, includedSubs) {
const siteName = docsJson.name || "Telnyx";
const siteDescription = docsJson.description || "";
const tabOrder = deriveTabOrder(docsJson);

let out = "";
out += `# ${siteName}\n`;
out += `> ${siteDescription}\n\n`;
out += `Telnyx developer documentation (${BASE_URL}), split into per-section and per-subsection files so agents can load only the relevant product area. Each section links a concise index (page links and descriptions, plus that section's API endpoints) and a \`-full.txt\` file carrying complete page content; the nested bullets are focused subsection files.\n\n`;
out += `## Telnyx developer resources\n\n`;
out += `- [Telnyx API Documentation](${BASE_URL}/internal/pages/api-reference-overview): REST API reference, endpoints, schemas, and examples by product.\n`;
out += `- [Telnyx API Authentication](${BASE_URL}/docs/development/api-fundamentals/authentication): Authenticate API requests with a Bearer API key.\n`;
out += `- [Telnyx Developer Portal](https://portal.telnyx.com): Manage your account and API keys in Mission Control.\n`;
out += `- [Telnyx MCP Server](${BASE_URL}/docs/development/mcp/remote-mcp): Connect AI agents to the remote Model Context Protocol server.\n`;
out += `- [Telnyx Agent Skills](https://www.skills.sh/team-telnyx/ai): Official Telnyx skills directory with per-skill setup and installation instructions.\n`;
out += `- [Telnyx OpenAPI Specification](${CONSOLIDATED_OPENAPI_SPEC_URL}): Machine-readable REST API contract.\n\n`;
out += USE_CASES_MD + WHY_TELNYX_MD + CONSTRAINTS_MD + FOR_AGENTS_MD;

out += `## Documentation sections\n\n`;
for (const tabName of tabOrder) {
const desc = TAB_DESCRIPTIONS[tabName] || "";
out += `- [${tabName}](${tabIndexUrl(tabName)}): ${desc} ([raw index](${BASE_URL}${rawAssetRoute(tabName)}), [full content](${tabFullUrl(tabName)}), [raw full content](${BASE_URL}${rawAssetRoute(tabName, undefined, true)}))\n`;
for (const subName of includedSubs.get(tabName) || []) {
out += ` - [${subName}](${subIndexUrl(tabName, subName)}) ([raw index](${BASE_URL}${rawAssetRoute(tabName, subName)}), [full](${subFullUrl(tabName, subName)}), [raw full](${BASE_URL}${rawAssetRoute(tabName, subName, true)}))\n`;
}
}
out += "\n";

// Pricing — agents need discoverable pricing to relay recommendations.
out += `## Pricing\n\n`;
out += `- [Pricing overview](${BASE_URL}/pricing.md): Pay-as-you-go rates for voice, messaging, phone numbers, wireless, AI inference, networking, and storage — full rate tables at https://telnyx.com/pricing and machine-readable pricing at https://telnyx.com/pricing.md.\n\n`;

// Reliability & Status — status page, machine-readable incident data, and
// SLA so agents source uptime/incident info from Telnyx, not aggregators.
out += RELIABILITY_MD;

// OpenAPI Specification — single link to the consolidated spec.
out += `## OpenAPI Specification\n\n`;
out += `- [Telnyx OpenAPI Specification (consolidated)](${CONSOLIDATED_OPENAPI_SPEC_URL}): Single OpenAPI 3.1 JSON covering every Telnyx REST API surface — paths, schemas, and webhooks.\n\n`;

return out;
}

// ---------------------------------------------------------------------------
// Output generation — per-section and per-subsection intermediate files
// ---------------------------------------------------------------------------

function appendApiReference(out, label, ops) {
if (!ops || ops.length === 0) return out;
const byTag = groupOpsByTag(ops);
out += `## API Reference (${label})\n\n`;
for (const [tag, tagOps] of byTag) {
out += `### ${tag}\n\n`;
for (const op of tagOps) {
// First line of the operation's spec description — gives agents a
// quotable summary per endpoint. Markdown links are flattened to
// their text so truncation can't leave broken syntax. Shards skip
// these to stay <50K.
const d = shortDescription(
(op.description || "").replace(/\[([^\]]*)\]$[^)]*$/g, "$1"),
160
);
out += d
? `- [${op.title}](${BASE_URL}${op.url}.md): ${d}\n`
: `- [${op.title}](${BASE_URL}${op.url}.md)\n`;
}
out += "\n";
}
return out;
}

function generateTabLlmsTxt(tabName, groups, tabOps, tabSubs) {
const desc = TAB_DESCRIPTIONS[tabName] || "";
let out = "";
out += `# Telnyx ${tabName} — Documentation Index\n`;
out += `> ${desc}. One section of the Telnyx developer docs (${BASE_URL}).\n`;
out += `> This file: ${tabIndexUrl(tabName)} · Root index: ${BASE_URL}/llms.txt\n\n`;

if (tabSubs && tabSubs.length > 0) {
out += `## Subsections\n\n`;
out += `Focused per-subsection index files:\n\n`;
for (const subName of tabSubs) {
out += `- [${subName}](${subIndexUrl(tabName, subName)})\n`;
}
out += "\n";
}

for (const [groupName, groupPages] of Object.entries(groups)) {
if (Object.keys(groups).length > 1) {
out += `## ${groupName}\n\n`;
}
for (const page of groupPages) {
const d = shortDescription(page.description);
out += d
? `- [${page.title}](${toMdUrl(page.url)}): ${d}\n`
: `- [${page.title}](${toMdUrl(page.url)})\n`;
}
out += "\n";
}

return appendApiReference(out, tabName, tabOps);
}

function generateTabLlmsFullTxt(tabName, groups, tabOps, tabSubs) {
const desc = TAB_DESCRIPTIONS[tabName] || "";
let out = "";
out += `# Telnyx ${tabName} — Full Documentation\n`;
out += `> ${desc}. Complete page content for the ${tabName} section of the Telnyx developer docs (${BASE_URL}).\n`;
out += `> This file: ${tabFullUrl(tabName)} · Root index: ${BASE_URL}/llms.txt\n\n`;

if (tabSubs && tabSubs.length > 0) {
out += `## Subsections\n\n`;
out += `Focused per-subsection full-content files:\n\n`;
for (const subName of tabSubs) {
out += `- [${subName}](${subFullUrl(tabName, subName)})\n`;
}
out += "\n";
}

for (const [groupName, groupPages] of Object.entries(groups)) {
out += `## ${groupName}\n\n`;
for (const page of groupPages) {
out += `### ${page.title}\n\n`;
if (page.url) {
out += `> Source: ${toMdUrl(page.url)}\n\n`;
}
out += page.content;
out += "\n\n---\n\n";
}
}

// Endpoint pages are generated from OpenAPI specs (no MDX source), so the
// full file links them rather than inlining.
return appendApiReference(out, tabName, tabOps);
}

function generateSubLlmsTxt(tabName, subName, innerGroups, subOps) {
let out = "";
out += `# Telnyx ${tabName}: ${subName} — Documentation Index\n`;
out += `> ${subName} documentation within the ${tabName} section of the Telnyx developer docs (${BASE_URL}).\n`;
out += `> This file: ${subIndexUrl(tabName, subName)} · Root index: ${BASE_URL}/llms.txt\n\n`;

const namedInner = [...innerGroups.keys()].filter((n) => n);
const useHeadings = namedInner.length > 1 || innerGroups.size > 1;
for (const [innerName, innerPages] of innerGroups) {
if (useHeadings && innerName) {
out += `## ${innerName}\n\n`;
}
for (const page of innerPages) {
const d = shortDescription(page.description);
out += d
? `- [${page.title}](${toMdUrl(page.url)}): ${d}\n`
: `- [${page.title}](${toMdUrl(page.url)})\n`;
}
out += "\n";
}

return appendApiReference(out, subName, subOps);
}

function generateSubLlmsFullTxt(tabName, subName, innerGroups, subOps) {
let out = "";
out += `# Telnyx ${tabName}: ${subName} — Full Documentation\n`;
out += `> Complete page content for ${subName} (${tabName} section) of the Telnyx developer docs (${BASE_URL}).\n`;
out += `> This file: ${subFullUrl(tabName, subName)} · Root index: ${BASE_URL}/llms.txt\n\n`;

for (const [innerName, innerPages] of innerGroups) {
if (innerName) {
out += `## ${innerName}\n\n`;
}
for (const page of innerPages) {
out += `### ${page.title}\n\n`;
if (page.url) {
out += `> Source: ${toMdUrl(page.url)}\n\n`;
}
out += page.content;
out += "\n\n---\n\n";
}
}

return appendApiReference(out, subName, subOps);
}

// ---------------------------------------------------------------------------
// Output generation — site-wide llms-full.txt (committed to repo)
// ---------------------------------------------------------------------------

function generateLlmsFullTxt(docsJson, includedSubs) {
const siteName = docsJson.name || "Telnyx";
const siteDescription = docsJson.description || "";
const tabOrder = deriveTabOrder(docsJson);

let out = "";
out += `# ${siteName} — Full Documentation\n`;
out += `> ${siteDescription}\n\n`;
out += `Complete Telnyx developer documentation, split into per-area full-content files (the combined corpus is ~3.4M characters — far past single-request agent limits). Each link below carries the complete page content for its area; this file holds authentication, quickstart examples, and the map. Lightweight per-area indexes are listed in [llms.txt](${BASE_URL}/llms.txt).\n\n`;
out += USE_CASES_MD + CONSTRAINTS_MD + FOR_AGENTS_MD + AUTH_QUICKSTART_MD;

out += `## Per-area full documentation\n\n`;
for (const tabName of tabOrder) {
out += `- [${tabName} — full content](${tabFullUrl(tabName)}): ${TAB_DESCRIPTIONS[tabName] || ""}\n`;
for (const subName of includedSubs.get(tabName) || []) {
out += ` - [${subName} — full content](${subFullUrl(tabName, subName)})\n`;
}
}
out += "\n" + RELIABILITY_MD;
out += `## OpenAPI Specification\n\n`;
out += `- [Telnyx OpenAPI Specification (consolidated)](${CONSOLIDATED_OPENAPI_SPEC_URL}): Single OpenAPI 3.1 JSON covering every Telnyx REST API surface.\n\n`;
return out;
}

// ---------------------------------------------------------------------------
// Mintlify-native llms pages (committed) — one pair per product/subsection
// ---------------------------------------------------------------------------

function landingBase(tabName, subName) {
return `${TAB_SLUGS[tabName]}-${subsectionSlug(subName)}`;
}

function landingPageRefs(tabName, subName) {
// Preserve the public machine-readable routes from the former standalone
// Development and Other APIs tabs after they move under Fundamentals.
if (tabName === "Fundamentals" && subName === "Development") {
return ["docs/development/llms-txt/index", "docs/development/llms-txt-full/index"];
}
if (tabName === "Fundamentals" && subName === "Other APIs") {
return [
"docs/development/llms/other-apis-llms-txt/index",
"docs/development/llms/other-apis-llms-full-txt/index",
];
}
const base = landingBase(tabName, subName);
// Refs MUST end in /index. Mintlify's nav indexer only reads a page's
// frontmatter (title/sidebarTitle) when the docs.json ref explicitly
// targets the index file; a bare directory ref makes the sidebar fall
// back to humanizing the slug ("Calling voice api llms txt"). The
// known-good entries (docs/development/agent-skills/index, the MCP pages)
// all use the explicit /index form. URLs are unchanged — Mintlify
// serves /index at /.
return [
`docs/development/llms/${base}-llms-txt/index`,
`docs/development/llms/${base}-llms-full-txt/index`,
];
}

// Generated llms content is valid Markdown but may contain JSX-like tags or
// bare object examples that MDX would interpret. Preserve Markdown structure
// while escaping only MDX-significant characters outside fenced code blocks.
function makeGeneratedContentMdxSafe(content) {
let fence = null;
return content
.split("\n")
.map((line) => {
line = line.replace(/\t/g, " ").replace(/[ \t]+$/, "");
const marker = line.match(/^\s*(`{3,}|~{3,})/);
if (marker) {
if (!fence) fence = marker[1][0];
else if (fence === marker[1][0]) fence = null;
return line;
}
if (fence) return line;
return line
.replace(/
path.join(REPO_ROOT, ref.replace(/\/index$/, ""))
);
}

function writeLandingPages(includedSubs) {
let count = 0;
for (const [tabName, subs] of includedSubs) {
if (subs.length === 0) continue;

// Every top-level product gets a Mintlify-native index and full-content
// page. These replace the bucket-hosted /llms/.txt artifacts.
const slug = TAB_SLUGS[tabName];
const [tabTxtDir, tabFullDir] = tabLandingDirs(tabName);
fs.mkdirSync(tabTxtDir, { recursive: true });
fs.mkdirSync(tabFullDir, { recursive: true });
fs.writeFileSync(
path.join(tabTxtDir, "index.mdx"),
generateTabLandingTxtMdx(tabName),
"utf8"
);
fs.writeFileSync(
path.join(tabFullDir, "index.mdx"),
generateTabLandingFullMdx(tabName),
"utf8"
);
count += 2;

for (const subName of subs) {
const [txtDir, fullDir] = landingPageDirs(tabName, subName);
fs.mkdirSync(txtDir, { recursive: true });
fs.mkdirSync(fullDir, { recursive: true });
fs.writeFileSync(
path.join(txtDir, "index.mdx"),
generateLandingTxtMdx(tabName, subName),
"utf8"
);
fs.writeFileSync(
path.join(fullDir, "index.mdx"),
generateLandingFullMdx(tabName, subName),
"utf8"
);
count += 2;
}
}
return count;
}

// ---------------------------------------------------------------------------
// docs.json sidebar updater — "For AI Agents" group in every subsection
// ---------------------------------------------------------------------------

const AI_AGENTS_GROUP = "For AI Agents";
// Names to recognize when removing previously generated groups — includes the
// legacy emoji-prefixed form so a rename never leaves duplicates behind.
const AI_AGENTS_GROUP_NAMES = new Set([AI_AGENTS_GROUP, "🤖 For AI Agents"]);

// Tabs whose llms sidebar is consolidated into their single top-level
// "For AI Agents" group: only the tab-level landing pair is listed in the
// navigation. Per-subsection pages are still written and served — Mintlify
// renders pages absent from docs.json as hidden pages (reachable by URL and
// their .md variants, verified live with /pricing and /compare); they are
// only left out of the sidebar, search, and sitemap. The tab-level pair
// already bundles every subsection's pages and endpoints inline.
const SIDEBAR_CONSOLIDATED_TABS = new Set(["Agent SDK"]);

function consolidatedTabLandingRefs(tabName) {
return tabLandingRefs(tabName);
}

// Per-subsection pages of consolidated tabs are deliberately hidden: they
// exist in the repo and serve at their URLs, but must not appear in
// docs.json navigation. The same applies to the tab-level landing pairs of
// non-consolidated tabs: each subsection sidebar lists only its own pair,
// and the tab pair stays reachable through the root llms.txt index.
// check-llms-native-routes.js enforces both sides.
function isHiddenLlmsPageRef(ref) {
if (ref === CODE_EXAMPLES_PAGE_REF) return true;
for (const tabName of SIDEBAR_CONSOLIDATED_TABS) {
if (tabLandingRefs(tabName).includes(ref)) continue;
if (ref.startsWith(`docs/development/llms/${TAB_SLUGS[tabName]}-`)) return true;
}
for (const tabName of Object.keys(TAB_SLUGS)) {
if (SIDEBAR_CONSOLIDATED_TABS.has(tabName)) continue;
if (tabLandingRefs(tabName).includes(ref)) return true;
}
return false;
}

function isGeneratedLlmsPageRef(page) {
return (
typeof page === "string" &&
(page.startsWith("docs/development/llms/") ||
page === "docs/development/llms-txt/index" ||
page === "docs/development/llms-txt-full/index")
);
}

function routeForLlmsPageRef(ref) {
return `/${ref.replace(/\/index$/, "")}`;
}

function rawAssetRoute(tabName, subName, full = false) {
const tabSlug = TAB_SLUGS[tabName];
const suffix = full ? "-full.txt" : ".txt";
if (tabName === "Fundamentals" && subName === "Development") {
return `/public/llms/development${suffix}`;
}
if (tabName === "Fundamentals" && subName === "Other APIs") {
return `/public/llms/other-apis${suffix}`;
}
return subName
? `/public/llms/${tabSlug}/${subsectionSlug(subName)}${suffix}`
: `/public/llms/${tabSlug}${suffix}`;
}

// Mintlify sidebar groups accept page references, not arbitrary href objects.
// Keep each generated page registered for publication, then redirect its HTML
// route to a distinct static text asset. Redirecting to its `.md` export is
// unsafe because Mintlify reapplies that rule to `.md` and creates `.md.md`.
function rawLlmsRedirects(includedSubs) {
const redirects = [];
for (const [tabName, subs] of includedSubs) {
if (subs.length === 0) continue;
const tabRefs = tabLandingRefs(tabName);
redirects.push(
{ source: routeForLlmsPageRef(tabRefs[0]), destination: rawAssetRoute(tabName) },
{ source: routeForLlmsPageRef(tabRefs[1]), destination: rawAssetRoute(tabName, null, true) },
);
for (const subName of subs) {
const refs = landingPageRefs(tabName, subName);
redirects.push(
{ source: routeForLlmsPageRef(refs[0]), destination: rawAssetRoute(tabName, subName) },
{ source: routeForLlmsPageRef(refs[1]), destination: rawAssetRoute(tabName, subName, true) },
);
}
}
return redirects;
}

function isGeneratedRawLlmsRedirect({ source, destination }) {
return (
typeof source === "string" &&
typeof destination === "string" &&
(destination === `${source}.md` || /^\/(?:public\/)?llms\/.+\.txt$/.test(destination)) &&
(/^\/docs\/development\/llms\//.test(source) ||
source === "/docs/development/llms-txt" ||
source === "/docs/development/llms-txt-full")
);
}

function rawLlmsAssetContent(source) {
const normalized = source
.split("\n")
.map((line) => line.replace(/\t/g, " ").trimEnd())
.join("\n")
.trimEnd();
// Mintlify serves nested static .txt files without a charset parameter.
// A UTF-8 BOM preserves Unicode when browsers otherwise assume Windows-1252.
return `\uFEFF${normalized}\n`;
}

function writeRawLlmsAssets(includedSubs) {
fs.rmSync(RAW_LLMS_DIR, { recursive: true, force: true });
fs.mkdirSync(RAW_LLMS_DIR, { recursive: true });
let count = 0;

for (const [tabName, subs] of includedSubs) {
if (subs.length === 0) continue;
const tabSlug = TAB_SLUGS[tabName];
for (const fileName of [`${tabSlug}.txt`, `${tabSlug}-full.txt`]) {
const source = fs.readFileSync(path.join(LLMS_OUT_DIR, fileName), "utf8");
fs.writeFileSync(
path.join(RAW_LLMS_DIR, fileName),
rawLlmsAssetContent(source),
"utf8",
);
count++;
}
for (const subName of subs) {
const subSlug = subsectionSlug(subName);
for (const full of [false, true]) {
const fileName = `${subSlug}${full ? "-full" : ""}.txt`;
const source = fs.readFileSync(path.join(LLMS_OUT_DIR, tabSlug, fileName), "utf8");
const destination = path.join(REPO_ROOT, rawAssetRoute(tabName, subName, full).slice(1));
fs.mkdirSync(path.dirname(destination), { recursive: true });
fs.writeFileSync(
destination,
rawLlmsAssetContent(source),
"utf8",
);
count++;
}
}
}
return count;
}

// Idempotent: generated per-subsection AI-agents entries are rebuilt on every
// run, while authored entries such as MCP and Agent Skills are preserved.
function updateDocsJsonSidebar(includedSubs, docsJsonPath = DOCS_JSON_PATH) {
const raw = fs.readFileSync(docsJsonPath, "utf8");
const docsJson = JSON.parse(raw);
let updated = 0;

// Consolidated tabs list only the tab-level landing pair; per-subsection
// pages stay published as hidden pages, out of the nav. Preserve
// hand-managed entries such as the Development MCP and Agent Skills pages.
// `entries` holds group objects (tab.groups, Home's groups) or the mixed
// page list of the Home "Other APIs" group.
const rebuildConsolidatedGroup = (entries, tabName, additionalAuthoredPages = []) => {
const generatedPages = consolidatedTabLandingRefs(tabName);
const existing = entries.find(
(entry) => entry && typeof entry === "object" && AI_AGENTS_GROUP_NAMES.has(entry.group)
);
const authoredPages = [
...(existing?.pages || []).filter((page) => !isGeneratedLlmsPageRef(page)),
...additionalAuthoredPages,
];
if (existing) {
existing.group = AI_AGENTS_GROUP;
existing.pages = [...authoredPages, ...generatedPages];
} else {
entries.push({ group: AI_AGENTS_GROUP, pages: [...authoredPages, ...generatedPages] });
}
updated++;
};

for (const tab of docsJson.navigation?.tabs || []) {
const tabName = tab.tab;
const subs = new Set(includedSubs.get(tabName) || []);
const consolidated = SIDEBAR_CONSOLIDATED_TABS.has(tabName);

if (tab.menu) {
for (const m of tab.menu) {
const n = m.item;
if (!n || !subs.has(n)) continue;
const existing = (m.groups || []).find((g) => AI_AGENTS_GROUP_NAMES.has(g.group));
const authoredPages = (existing?.pages || []).filter(
(page) => !isGeneratedLlmsPageRef(page)
);
m.groups = (m.groups || []).filter((g) => !AI_AGENTS_GROUP_NAMES.has(g.group));
if (consolidated) continue;
m.groups.push({
group: AI_AGENTS_GROUP,
pages: [...authoredPages, ...landingPageRefs(tabName, n)],
});
updated++;
}
} else if (tab.groups) {
for (const g of tab.groups) {
const n = g.group;
if (!n || !subs.has(n)) continue;
g.pages = (g.pages || []).filter(
(p) => !(p && typeof p === "object" && AI_AGENTS_GROUP_NAMES.has(p.group))
);
if (consolidated) continue;
g.pages.push({ group: AI_AGENTS_GROUP, pages: landingPageRefs(tabName, n) });
updated++;
}
}

// Consolidated tabs list only the tab-level landing pair; per-subsection
// pages stay published as hidden pages, out of the nav.
if (consolidated && tab.groups && subs.size > 0) {
rebuildConsolidatedGroup(tab.groups, tabName);
}
}

// Products division: every nested product tab is a legacy subsection;
// Home's groups are the Fundamentals family's subsections. Mutates the
// real docs.json nodes, so this walks the products shape directly instead
// of the read-only navigationTabs() view.
if (!docsJson.navigation?.tabs) {
for (const product of docsJson.navigation?.products || []) {
if (product.product === HOME_PRODUCT) {
const family = PRODUCT_TO_TAB[HOME_PRODUCT];
const subs = new Set(includedSubs.get(family) || []);
for (const g of product.groups || []) {
const n = g.group;
if (!n || !subs.has(n)) continue;
const existing = (g.pages || []).find(
(p) => p && typeof p === "object" && AI_AGENTS_GROUP_NAMES.has(p.group)
);
const authoredPages = (existing?.pages || []).filter(
(page) => !isGeneratedLlmsPageRef(page)
);
g.pages = (g.pages || []).filter(
(p) => !(p && typeof p === "object" && AI_AGENTS_GROUP_NAMES.has(p.group))
);
g.pages.push({
group: AI_AGENTS_GROUP,
pages: [...authoredPages, ...landingPageRefs(family, n)],
});
updated++;
}
continue;
}

const productFamilies = new Set();
const authoredPagesByFamily = new Map();
for (const nestedTab of product.tabs || []) {
const tabName = productFamilyForNestedTab(product.product, nestedTab.tab);
productFamilies.add(tabName);
const subs = new Set(includedSubs.get(tabName) || []);
if (!subs.has(nestedTab.tab)) continue;
const existing = (nestedTab.groups || []).find((g) => AI_AGENTS_GROUP_NAMES.has(g.group));
const authoredPages = (existing?.pages || []).filter(
(page) => !isGeneratedLlmsPageRef(page)
);
if (authoredPages.length > 0) {
authoredPagesByFamily.set(tabName, [
...(authoredPagesByFamily.get(tabName) || []),
...authoredPages,
]);
}
nestedTab.groups = (nestedTab.groups || []).filter(
(g) => !AI_AGENTS_GROUP_NAMES.has(g.group)
);
if (SIDEBAR_CONSOLIDATED_TABS.has(tabName)) continue;
nestedTab.groups.push({
group: AI_AGENTS_GROUP,
pages: [...authoredPages, ...landingPageRefs(tabName, nestedTab.tab)],
});
updated++;
}

// Consolidated families list only the family-level landing pair,
// carried in the suite's first nested tab (e.g. Agent SDK).
for (const family of productFamilies) {
if (!SIDEBAR_CONSOLIDATED_TABS.has(family)) continue;
if ((includedSubs.get(family) || []).length === 0) continue;
const firstTab = (product.tabs || [])[0];
if (firstTab && firstTab.groups) {
rebuildConsolidatedGroup(
firstTab.groups,
family,
authoredPagesByFamily.get(family) || []
);
}
}
}
}

docsJson.redirects = [
...(docsJson.redirects || []).filter(
(redirect) => !isGeneratedRawLlmsRedirect(redirect),
),
...rawLlmsRedirects(includedSubs),
];

fs.writeFileSync(docsJsonPath, JSON.stringify(docsJson, null, 2) + "\n", "utf8");
return updated;
}

// ---------------------------------------------------------------------------
// Cleanup old files
// ---------------------------------------------------------------------------

function cleanupOldFiles() {
// Remove old per-group public/llms/ directories
const llmsDir = path.join(PUBLIC_DIR, "llms");
if (fs.existsSync(llmsDir)) {
fs.rmSync(llmsDir, { recursive: true });
console.log(" ✓ Deleted old public/llms/");
}

// Remove old public/docs/development/ files
const devDir = path.join(PUBLIC_DIR, "development");
if (fs.existsSync(devDir)) {
fs.rmSync(devDir, { recursive: true });
console.log(" ✓ Deleted old public/docs/development/");
}

// Remove old per-group MDX directories
const oldDirs = [
path.join(REPO_ROOT, "docs", "development", "agent-llms-full-txt"),
path.join(REPO_ROOT, "docs", "development", "agent-llms-txt"),
];
for (const dir of oldDirs) {
if (fs.existsSync(dir)) {
fs.rmSync(dir, { recursive: true });
console.log(` ✓ Deleted old ${path.relative(REPO_ROOT, dir)}/`);
}
}

// Remove legacy .well-known API Reference shards — Mintlify never served
// .txt files from .well-known/ (only .json/.yaml static assets work).
const wellKnownDir = path.join(REPO_ROOT, ".well-known");
if (fs.existsSync(wellKnownDir)) {
for (const name of fs.readdirSync(wellKnownDir)) {
if (/^api-reference-\d+-llms\.txt$/.test(name)) {
fs.rmSync(path.join(wellKnownDir, name));
console.log(` ✓ Deleted legacy .well-known/${name}`);
}
}
}

// Landing pages and llms-out/ are fully generated — reset both so renamed
// or removed subsections never leave stale files behind.
if (fs.existsSync(LANDING_DIR)) {
fs.rmSync(LANDING_DIR, { recursive: true });
}
if (fs.existsSync(LLMS_OUT_DIR)) {
fs.rmSync(LLMS_OUT_DIR, { recursive: true });
}
}

// ---------------------------------------------------------------------------
// Main
// ---------------------------------------------------------------------------

async function main() {
console.log("Reading docs.json...");
const docsJson = readDocsJson();

console.log("Walking navigation tree...");
const pages = walkNavigation(docsJson);
console.log(`Found ${pages.length} documentation pages`);

// Count per tab
const tabCounts = {};
for (const page of pages) {
tabCounts[page.tab] = (tabCounts[page.tab] || 0) + 1;
}
for (const [tab, count] of Object.entries(tabCounts)) {
console.log(` ${tab}: ${count} pages`);
if (!TAB_SLUGS[tab] && !LLMS_EXCLUDED_TABS.has(tab)) {
console.warn(
` ⚠ Tab "${tab}" has no llms slug — deriveTabOrder will fail closed ` +
`(add the family to TAB_SLUGS or map the suite in PRODUCT_TO_TAB)`
);
}
}

// Subsections per tab, straight from docs.json
const subsByTab = deriveSubsections(docsJson);
const tabOrder = deriveTabOrder(docsJson);

// Collect OpenAPI specs (with tab + subsection attribution)
const openApiSpecs = collectOpenApiSpecs(docsJson);
console.log(`Found ${openApiSpecs.length} OpenAPI specs`);

// Expand each spec into per-operation entries (paths + 3.1 webhooks)
console.log("Expanding OpenAPI specs into per-operation entries...");
const { allOps, opsByTab, opsBySub } = await expandOpenApiOperations(openApiSpecs);
console.log(` Found ${allOps.length} operations across all specs`);

// Ensure output directories exist
if (!fs.existsSync(PUBLIC_DIR)) {
fs.mkdirSync(PUBLIC_DIR, { recursive: true });
}

// Clean up old files (also resets llms-out/ and docs/development/llms/)
console.log("\nCleaning up old files...");
cleanupOldFiles();
fs.mkdirSync(LLMS_OUT_DIR, { recursive: true });

const tabGroups = groupPagesByTab(pages);
const pagesBySub = groupPagesBySubsection(pages);

// Subsections that actually have content (pages or endpoints). Empty ones
// get no files, no sidebar entries, and no root index lines.
const includedSubs = new Map();
for (const tabName of tabOrder) {
const subs = [];
for (const subName of subsByTab.get(tabName) || []) {
const key = subKey(tabName, subName);
const hasPages = pagesBySub.has(key);
const hasOps = (opsBySub.get(key) || []).length > 0;
if (hasPages || hasOps) {
subs.push(subName);
} else {
console.warn(` ⚠ Subsection "${tabName} → ${subName}" has no pages or endpoints — skipping`);
}
}
includedSubs.set(tabName, subs);
}

// ---------------------------------------------------------------
// Per-section and per-subsection files → llms-out/
// ---------------------------------------------------------------
console.log("\nGenerating per-section files in llms-out/...");
let subFileCount = 0;
for (const tabName of tabOrder) {
const groups = tabGroups[tabName];
if (!groups) {
console.warn(` ⚠ No pages found for tab "${tabName}" — skipping`);
continue;
}
const tabOps = opsByTab.get(tabName) || [];
const slug = TAB_SLUGS[tabName];
const tabSubs = includedSubs.get(tabName) || [];

const indexText = generateTabLlmsTxt(tabName, groups, tabOps, tabSubs);
fs.writeFileSync(path.join(LLMS_OUT_DIR, `${slug}.txt`), indexText, "utf8");
const indexKb = (Buffer.byteLength(indexText, "utf8") / 1024).toFixed(1);

const fullText = generateTabLlmsFullTxt(tabName, groups, tabOps, tabSubs);
fs.writeFileSync(path.join(LLMS_OUT_DIR, `${slug}-full.txt`), fullText, "utf8");
const fullKb = (Buffer.byteLength(fullText, "utf8") / 1024).toFixed(1);

console.log(` → ${slug}.txt (${indexKb} KB) + ${slug}-full.txt (${fullKb} KB)`);

// Subsection files in llms-out//
if (tabSubs.length > 0) {
const tabDir = path.join(LLMS_OUT_DIR, slug);
fs.mkdirSync(tabDir, { recursive: true });
for (const subName of tabSubs) {
const key = subKey(tabName, subName);
const innerGroups = pagesBySub.get(key) || new Map();
const subOps = opsBySub.get(key) || [];
const subSlug = subsectionSlug(subName);

const subIndex = generateSubLlmsTxt(tabName, subName, innerGroups, subOps);
fs.writeFileSync(path.join(tabDir, `${subSlug}.txt`), subIndex, "utf8");

const subFull = generateSubLlmsFullTxt(tabName, subName, innerGroups, subOps);
fs.writeFileSync(path.join(tabDir, `${subSlug}-full.txt`), subFull, "utf8");

subFileCount += 2;
const iKb = (Buffer.byteLength(subIndex, "utf8") / 1024).toFixed(1);
const fKb = (Buffer.byteLength(subFull, "utf8") / 1024).toFixed(1);
console.log(` ↳ ${slug}/${subSlug}.txt (${iKb} KB) + ${slug}/${subSlug}-full.txt (${fKb} KB)`);
}
}
}
console.log(` Subsection files: ${subFileCount}`);

const rawAssetCount = writeRawLlmsAssets(includedSubs);
console.log(` Raw static assets: ${rawAssetCount} under public/llms/`);

// ---------------------------------------------------------------
// Root llms.txt (nested index) + site-wide llms-full.txt,
// committed to the repo. Mintlify serves these two names at the
// site root (custom files override its auto-generated versions);
// root files are the canonical public endpoints.
// ---------------------------------------------------------------
// Static snippet: production-ready Python code examples from
// team-telnyx/telnyx-code-examples. Inlined into llms-full.txt and served
// as its own hidden page; the root index links that page instead of
// inlining the snippet, which alone would consume 2/3 of the 50K budget.
// Update the snippet file to add/remove examples — no script changes needed.
const codeExamplesSnippet = fs.readFileSync(
path.join(__dirname, "code-examples-llms-snippet.md"),
"utf8"
).trimEnd();

console.log("\nGenerating root llms.txt (nested index)...");
const rootIndex =
generateRootLlmsIndex(docsJson, includedSubs) +
"\n" +
codeExamplesRootSection(codeExamplesSnippet);
const rootSize = Buffer.byteLength(rootIndex, "utf8");
fs.writeFileSync(path.join(REPO_ROOT, "llms.txt"), rootIndex, "utf8");
console.log(` → llms.txt (${(rootSize / 1024).toFixed(1)} KB)`);

console.log("Generating site-wide llms-full.txt...");
const llmsFullTxt = generateLlmsFullTxt(docsJson, includedSubs) + "\n" + codeExamplesSnippet + "\n";
fs.writeFileSync(path.join(REPO_ROOT, "llms-full.txt"), llmsFullTxt, "utf8");
const llmsFullTxtSize = (Buffer.byteLength(llmsFullTxt, "utf8") / (1024 * 1024)).toFixed(2);
console.log(` → llms-full.txt (${llmsFullTxtSize} MB)`);

// ---------------------------------------------------------------
// Sidebar landing pages + docs.json entries (committed)
// ---------------------------------------------------------------
console.log("\nGenerating sidebar landing pages...");
const landingCount = writeLandingPages(includedSubs);
console.log(` → ${landingCount} MDX pages under docs/development/llms/`);

writeCodeExamplesPage(codeExamplesSnippet);
console.log(" → docs/development/llms/code-examples/index.mdx (hidden page)");

console.log("Updating docs.json sidebar entries...");
const sidebarCount = updateDocsJsonSidebar(includedSubs);
console.log(` → ${sidebarCount} "${AI_AGENTS_GROUP}" subsection groups`);

// Validate docs.json round-trips as JSON
try {
JSON.parse(fs.readFileSync(DOCS_JSON_PATH, "utf8"));
console.log(" ✓ docs.json is valid JSON");
} catch (e) {
console.error(" ✗ docs.json is INVALID JSON:", e.message);
process.exit(1);
}

console.log("\nDone!");
}

module.exports = {
collectOpenApiSpecs,
deriveTabOrder,
collectOperationsFromSpec,
expandOpenApiOperations,
generateLandingTxtMdx,
generateRootLlmsIndex,
isHiddenLlmsPageRef,
landingPageRefs,
operationsForSpec,
rawLlmsAssetContent,
rawLlmsRedirects,
updateDocsJsonSidebar,
};

if (require.main === module) {
main().catch((err) => {
console.error(err);
process.exit(1);
});
}}}}}