diff --git a/fern/docs.yml b/fern/docs.yml index 48c3fd1571..76b47e5bd9 100644 --- a/fern/docs.yml +++ b/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: diff --git a/fern/products/home/pages/welcome.mdx b/fern/products/home/pages/welcome.mdx index 49c0930867..f4d128bb28 100644 --- a/fern/products/home/pages/welcome.mdx +++ b/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 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. + +### 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. diff --git a/fern/snippets/llms-hint.mdx b/fern/snippets/llms-hint.mdx index 503e0011b4..721a995052 100644 --- a/fern/snippets/llms-hint.mdx +++ b/fern/snippets/llms-hint.mdx @@ -1,3 +1,3 @@ - + diff --git a/scripts/check-md-exports.js b/scripts/check-md-exports.js index cc09d1d2d4..c6846bab6f 100644 --- a/scripts/check-md-exports.js +++ b/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; }, diff --git a/scripts/check-md-exports.test.js b/scripts/check-md-exports.test.js index eb25af8d40..ef8fa41e48 100644 --- a/scripts/check-md-exports.test.js +++ b/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']); }); diff --git a/scripts/llm-export-cases.json b/scripts/llm-export-cases.json index c84720d5ad..4455cfafec 100644 --- a/scripts/llm-export-cases.json +++ b/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", "