docs: improve llms.txt routing

fern/docs.yml

@@ -25,8 +25,11 @@ landing-page:
 
 agents:
   page-directive: >-
-    For a complete index of all SignalWire documentation pages, fetch
-    https://signalwire.com/docs/llms.txt
+    Fetch clean Markdown by appending `.md` to any page URL under
+    https://signalwire.com/docs or requesting it with the HTTP header
+    `Accept: text/markdown`. The root index at
+    https://signalwire.com/docs/llms.txt lists the available documentation
+    indexes.
 
 analytics:
   gtm:

fern/products/home/pages/welcome.mdx

@@ -2,7 +2,7 @@
 id: 0f7a51b9-708a-48fa-bccf-d9a449c4489c
 title: SignalWire Documentation
 slug: /
-description: Build powerful communication applications with SignalWire. Explore our REST APIs, Realtime SDKs, and comprehensive guides.
+description: Build voice, video, messaging, and AI applications with SignalWire developer tools and implementation guides.
 hide-toc: true
 layout: custom
 ---
@@ -122,30 +122,160 @@ layout: custom
 <llms-only>
 
 SignalWire is a programmable communications platform for building voice, video, messaging, and AI applications.
-Use the build type or interface below to choose the shortest path into the documentation.
-
-## Choose what to build
-
-| Goal | Start here | Use it for |
-|---|---|---|
-| AI voice agent | [AI application path](/docs/platform/getting-started#ai-application) | LLM-powered phone agents and virtual assistants |
-| Browser or mobile experience | [Browser or mobile path](/docs/platform/getting-started#browser-or-mobile-app) | WebRTC voice, video, and chat in an application |
-| Server application | [Server application path](/docs/platform/getting-started#server-application) | Backend call routing, messaging, interactive voice response, and realtime control |
-| No-code application | [No-code and low-code path](/docs/platform/getting-started#no-code--low-code) | Dashboard AI agents and drag-and-drop call flows |
-| Twilio migration | [Compatibility API](/docs/compatibility-api) | Existing applications that use Twilio-compatible REST APIs or TwiML-compatible markup |
-
-## Choose an interface
-
-| Interface | Start here | Best fit |
-|---|---|---|
-| REST APIs | [REST API documentation](/docs/apis) | Programmatic management of calls, messages, phone numbers, video rooms, and resources |
-| SWML | [SignalWire Markup Language](/docs/swml) | Declarative call and messaging applications returned from webhooks or hosted by SignalWire |
-| Server SDKs | [Server SDK documentation](/docs/server-sdks) | AI agents and realtime call control in a supported programming language |
-| Browser SDK | [Browser SDK documentation](/docs/browser-sdk) | Voice, video, and chat inside browser applications |
-| Call Flow Builder | [Call Flow Builder documentation](/docs/call-flow-builder) | Visual, no-code voice applications |
-| Platform and Dashboard | [Platform documentation](/docs/platform) | Spaces, credentials, phone numbers, resources, and operational configuration |
-| Wirestarter | [Wirestarter documentation](/docs/platform/wirestarter) | Scaffolding a new SignalWire project |
-| SWSH | [SWSH documentation](/docs/platform/swsh) | Interactively testing SWML scripts and API calls |
+Start with the navigation and platform sections, then choose the path that matches how your application takes part.
+
+## Navigate the documentation
+
+- Treat the [root `llms.txt`](https://signalwire.com/docs/llms.txt) as an orientation page and directory, not an exhaustive list of documentation pages. The available documentation indexes appear under `## Products` at the bottom of the file.
+- Fetch a documentation page as clean Markdown by appending `.md` to its URL or requesting it with the HTTP header `Accept: text/markdown`.
+- Open the relevant documentation index to discover its page links.
+- If a page is not listed in the root index, check the relevant documentation index before concluding that the documentation does not contain it.
+
+## Choose a path
+
+Each heading below describes a setup task or a way an application can handle communication. Links go to a landing or getting-started page; choose the option that matches your architecture.
+
+### Learn the platform and get started
+
+- [Get started](/docs/platform/getting-started): Walkthrough of your Space, the build paths, and the core concepts.
+- [Create an account](/docs/platform/signing-up-for-a-space): Open a new Space on the SignalWire platform.
+- [API credentials](/docs/platform/your-signalwire-api-space): Find the Project ID and API token that SDKs and APIs use to authenticate.
+- [Resources](/docs/platform/resources): Communication entities such as AI agents, SignalWire Markup Language (SWML) scripts, Subscribers, and Video Rooms.
+- [Addresses](/docs/platform/addresses): The aliases, phone numbers, and Session Initiation Protocol (SIP) URIs that make a Resource reachable.
+- [Subscribers](/docs/platform/subscribers): Resources that represent users, and the basis of user management.
+- [Phone numbers](/docs/platform/phone-numbers): Buy, port, and configure phone numbers.
+- [Webhooks](/docs/platform/webhooks): Receive events about calls and messages over HTTP.
+
+### Understand the communication channels
+
+- [Calling](/docs/platform/calling): Voice, video, fax, and AI on one platform.
+- [Voice](/docs/platform/voice): Programmable calling with integrated AI.
+- [Video](/docs/platform/video): Programmable video conferencing.
+- [Fax](/docs/platform/fax): Send and receive faxes.
+- [Messaging](/docs/platform/messaging): Programmable Short Message Service (SMS) and Multimedia Messaging Service (MMS).
+- [WhatsApp](/docs/platform/messaging/whatsapp): Send and receive WhatsApp messages.
+- [Chat](/docs/platform/chat): Programmable chat for applications.
+- [AI](/docs/platform/ai): Conversational agents directed by your code, data, and business rules.
+
+### Set up a local development and testing environment
+
+- [WireStarter](/docs/platform/wirestarter)
+
+### Configure and manage a Space from the command line
+
+- [SWSH](/docs/platform/swsh)
+
+### Return call or messaging instructions from your server over HTTP, one synchronous request at a time
+
+- [SWML](/docs/swml/guides)
+- [Server SDKs for AI agents](/docs/server-sdks/guides/quickstart)
+
+### Handle communication over a persistent WebSocket connection, issuing commands and reacting to events asynchronously
+
+- [Server SDKs, Relay client](/docs/server-sdks/guides/relay-client)
+- [Browser SDK](/docs/browser-sdk/v4/guides/overview)
+
+### Act on a live call, or send a message, with a single HTTP request
+
+- [Server SDKs](/docs/server-sdks)
+- [REST APIs](/docs/apis)
+
+### Run an AI agent in voice or text conversations
+
+- [Server SDKs](/docs/server-sdks/guides/quickstart)
+- [SWML](/docs/swml/guides)
+- [Dashboard AI agent](/docs/platform/resources#in-the-dashboard)
+
+### Build a voice application with low-code or no-code tools and no server of your own
+
+- [Call Flow Builder](/docs/call-flow-builder)
+- [SWML](/docs/swml/guides)
+
+### Browser or mobile app calling and chat
+
+- [Browser SDK](/docs/browser-sdk/v4/guides/overview)
+- [REST APIs](/docs/apis)
+
+### Video conferences
+
+- [Browser SDK](/docs/browser-sdk/v4/guides/overview)
+- [REST APIs](/docs/apis)
+- [Video](/docs/platform/video)
+
+### Send and receive SMS and MMS
+
+- [Server SDKs](/docs/server-sdks)
+- [SWML](/docs/swml/guides)
+- [REST APIs](/docs/apis)
+- [Messaging](/docs/platform/messaging)
+
+### Provision and manage numbers, resources, subscribers, and logs
+
+- [Server SDKs](/docs/server-sdks)
+- [REST APIs](/docs/apis)
+
+### Migrate a Twilio application
+
+- [Compatibility API](/docs/compatibility-api)
+
+## Popular features
+
+Feature pages are grouped by channel. SDK pages come first when available, followed by SWML or platform pages when no SDK feature page exists.
+
+### Calling
+
+- [Call recording](/docs/swml/guides/record-calls): Record an ongoing call with a hosted SWML script and access the recording in your Space.
+- [Call transfer](/docs/server-sdks/guides/call-transfer): Transfer a call to a phone number, SIP endpoint, or SWML document.
+- [Real-time transcription](/docs/server-sdks/reference/python/relay/call/live-transcribe): Start or stop live transcription on a call.
+- [Live translation](/docs/server-sdks/reference/python/relay/call/live-translate): Start or stop live translation on a call.
+- [Audio streaming](/docs/server-sdks/reference/python/relay/call/stream): Stream call audio to a WebSocket endpoint.
+- [Conferencing](/docs/server-sdks/reference/python/relay/call/join-conference): Join a call to an ad-hoc audio conference.
+- [Secure payments](/docs/server-sdks/reference/python/relay/call/pay): Collect payment information on a call.
+- [Collect caller input](/docs/server-sdks/reference/python/relay/call/play-and-collect): Play audio and collect speech or key presses.
+- [Answering machine detection](/docs/server-sdks/reference/python/relay/call/detect): Detect answering machines, fax tones, or digits on a call.
+- [Noise reduction](/docs/server-sdks/reference/python/relay/call/denoise): Start noise reduction on a call.
+- [Call queues](/docs/server-sdks/reference/python/relay/call/queue-enter): Place a call into a named queue.
+- [Text-to-speech voices](/docs/platform/voice/tts): Supported providers, voices, and languages.
+- [Caller ID and Calling Name (CNAM)](/docs/platform/voice/how-to-set-caller-id-or-cnam): Configure an outbound number and a caller name that supported carriers can display.
+- [STIR/SHAKEN caller verification](/docs/platform/voice/stir-shaken): STIR (Secure Telephone Identity Revisited) and SHAKEN (Secure Handling of Asserted information using toKENs) provide caller identity attestation for outbound calls.
+- [SIP](/docs/platform/voice/sip): SIP trunking, SIP credentials, and bring your own carrier.
+- [Web Real-Time Communication (WebRTC)](/docs/platform/voice/what-is-webrtc): How SignalWire uses WebRTC for real-time media.
+
+### Video
+
+- [Voice and video in the browser](/docs/browser-sdk/v4/guides/build-voice-video): Build a calling or video experience with the Browser SDK.
+- [Screen sharing](/docs/browser-sdk/v4/guides/screen-sharing): Share a screen in a video call.
+- [Layouts and participant views](/docs/browser-sdk/v4/guides/layouts): Arrange participants in a video call.
+- [Device management](/docs/browser-sdk/v4/guides/device-management): Choose cameras, microphones, and speakers.
+- [Click-to-call widget](/docs/browser-sdk/v4/guides/click-to-call-widget): Add a call button to a public web page.
+- [Join a video room from a call](/docs/server-sdks/reference/python/relay/call/join-room): Join a video or audio room from a call.
+
+### Messaging
+
+- [Chat in the browser](/docs/browser-sdk/v4/guides/messaging-chat): Add messaging and chat to a browser app.
+- [Send SMS and MMS](/docs/server-sdks/reference/python/relay/client/send-message): Send an outbound SMS or MMS message.
+- [Campaign Registry registration for 10-digit long code (10DLC) numbers](/docs/platform/messaging/campaign-registry/registration): Register a brand and campaign for business SMS in the United States.
+- [Toll-free verification](/docs/platform/messaging/toll-free-numbers): Verify a toll-free number for messaging.
+- [Hosted messaging](/docs/platform/messaging/hosted-messaging): Port messaging service only to SignalWire.
+- [Delivery best practices](/docs/platform/messaging/sms-best-practices): Improve message delivery rates.
+- [Character limits](/docs/platform/messaging/character-limits): How message segments are measured and priced.
+- [MIME types](/docs/platform/messaging/mime-types): Media types supported in MMS.
+
+### AI
+
+- [Tool calling with the SignalWire AI Gateway (SWAIG)](/docs/server-sdks/guides/swaig): Let the agent call functions on your backend through webhooks.
+- [Skills](/docs/server-sdks/guides/understanding-skills): Add reusable capabilities to an agent without custom code.
+- [Prompts and the Prompt Object Model (POM)](/docs/server-sdks/guides/prompts-pom): Build structured prompts with sections, subsections, and bullets.
+- [Contexts and workflows](/docs/server-sdks/guides/contexts-workflows): Multi-step conversation flows with branching and validation.
+- [DataMap](/docs/server-sdks/guides/data-map): Call REST APIs from the agent without running code on your server.
+- [Search and knowledge](/docs/server-sdks/guides/search-knowledge): Add knowledge search to an agent with vector indexes.
+- [Model Context Protocol (MCP) Gateway](/docs/server-sdks/guides/mcp-gateway): Connect MCP servers to an agent.
+- [Multi-agent servers](/docs/server-sdks/guides/multi-agent): Run several agents on one server.
+- [Voice and language](/docs/server-sdks/guides/voice-language): Configure the agent's voice, language, and pronunciation.
+- [AI sidecar](/docs/swml/reference/calling/ai-sidecar): Attach a real-time AI observer to a live call.
+- [Prompt engineering](/docs/platform/ai/prompt-engineering): Where to place instructions and how to structure a prompt.
+- [Conversation analytics](/docs/platform/ai/analytics): Analyze conversations with post-prompt reports and debug webhooks.
+- [Sensitive content](/docs/platform/ai/content-redaction): Redact sensitive content from AI conversations.
 
 [Create a SignalWire account](https://signalwire.com/signup), or follow the [Platform getting-started guide](/docs/platform/getting-started) to configure an existing Space.
 

fern/snippets/llms-hint.mdx

@@ -1,3 +1,3 @@
 <llms-ignore>
-  <div className="llms-hint" aria-hidden="true">For AI agents: the complete SignalWire documentation index is at https://signalwire.com/docs/llms.txt. Append /llms.txt to any URL for a section-level index, or .md to any page URL for its markdown version.</div>
+  <div className="llms-hint" aria-hidden="true">For AI agents: Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.</div>
 </llms-ignore>

scripts/check-md-exports.js

@@ -205,6 +205,14 @@ const TERM_RE = /^\*\*`[^`\n]+`\*\*/m;
 const PARAMS_HEADING_RE = /^#{2,4}\s+\**(Properties|Parameters|Attributes|Fields|Variables|Returns)\b/im;
 const HR_RE = /^\s*---\s*$/m;
 
+/** Remove a Fern page directive blockquote when it appears before the H1. */
+function stripLeadingPageDirective(body) {
+  return body.replace(
+    /^(?:[ \t]*\n)*(?:[ \t]*>[^\n]*(?:\n|$))+(?:[ \t]*\n)*(?=[ \t]*#\s)/,
+    '',
+  );
+}
+
 /**
  * Each check receives { body, stripped } and returns a message string (finding)
  * or null (clean). Severity tiers: error affects the exit code; warn is surfaced;
@@ -215,7 +223,7 @@ const CHECKS = [
     id: 'soft-404',
     severity: 'error',
     test({ body }) {
-      return body.trimStart().startsWith('# Page Not Found')
+      return stripLeadingPageDirective(body).trimStart().startsWith('# Page Not Found')
         ? 'listed in llms.txt but the .md export is a "Page Not Found" stub'
         : null;
     },
@@ -224,9 +232,9 @@ const CHECKS = [
     id: 'empty-body',
     severity: 'error',
     test({ body }) {
-      const content = body
+      const content = stripLeadingPageDirective(body)
         .split('\n')
-        .filter((l) => !/^>\s*For a complete index/.test(l) && !/^#\s/.test(l) && l.trim() !== '')
+        .filter((l) => !/^#\s/.test(l) && l.trim() !== '')
         .join('\n');
       return content.length < 80 ? `body is nearly empty (${content.length} chars of content)` : null;
     },

scripts/check-md-exports.test.js

@@ -197,12 +197,17 @@ test('a "Page Not Found" stub is a soft-404 error', () => {
   assert.deepEqual(checkIds(body, { severity: 'error' }), ['soft-404']);
 });
 
+test('a page directive does not hide a "Page Not Found" stub', () => {
+  const body = `> Fetch clean Markdown from this deliberately long page directive that may change independently of the checker.\n\n# Page Not Found\n`;
+  assert.deepEqual(checkIds(body, { severity: 'error' }), ['soft-404']);
+});
+
 test('HTTP 404 on a listed page is a hard-404 error', () => {
   assert.deepEqual(checkIds('irrelevant', { status: 404 }), ['hard-404']);
 });
 
 test('a nearly empty body is an error', () => {
-  const body = '> For a complete index of all SignalWire documentation pages, fetch x\n\n# title\n\nshort.\n';
+  const body = '> Fetch clean Markdown from this deliberately long page directive that may change independently of the checker.\n\n# title\n\nshort.\n';
   assert.deepEqual(checkIds(body, { severity: 'error' }), ['empty-body']);
 });
 

scripts/llm-export-cases.json

@@ -3,27 +3,41 @@
     "name": "Documentation homepage",
     "path": ".md",
     "contains": [
+      "Build voice, video, messaging, and AI applications with SignalWire developer tools and implementation guides.",
       "SignalWire is a programmable communications platform",
-      "## Choose what to build",
+      "## Navigate the documentation",
+      "## Choose a path",
+      "[WireStarter](/docs/platform/wirestarter)",
+      "## Popular features",
       "[Platform getting-started guide](/docs/platform/getting-started)",
       "Twilio and TwiML are trademarks"
     ],
     "notContains": [
       "class=\"fern-page-heading",
       "<Button",
-      "<div class=\"lp-page-container"
+      "<div class=\"lp-page-container",
+      "## Choose what to build",
+      "## Choose an interface",
+      "|---|"
     ]
   },
   {
     "name": "Root llms.txt orientation",
     "path": "/llms.txt",
     "contains": [
+      "Build voice, video, messaging, and AI applications with SignalWire developer tools and implementation guides.",
       "SignalWire is a programmable communications platform",
-      "## Choose what to build"
+      "## Navigate the documentation",
+      "## Choose a path",
+      "[WireStarter](/docs/platform/wirestarter)",
+      "## Popular features"
     ],
     "notContains": [
       "class=\"fern-page-heading",
-      "<div class=\"lp-page-container"
+      "<div class=\"lp-page-container",
+      "## Choose what to build",
+      "## Choose an interface",
+      "|---|"
     ]
   },
   {