Serve a hand-maintained root llms.txt - #665
Open
Devon-White wants to merge 20 commits into
Open
Conversation
Fern generated the root llms.txt from the landing page's <llms-only> block and appended its own 'Instructions for AI Agents' section (with an MCP server link). Move the index into fern/llms.txt, point agents.llms-txt at it, and drop the Fern-injected section. Product-level indexes stay generated. The homepage keeps a one-line pointer to llms.txt. Export checks and repo docs updated to match.
Contributor
…ot llms.txt fern/llms.txt links product indexes on the production host, so a preview crawl found no child indexes. Rewrite those links onto --base-url before following them.
…gelog links for setup docs The trademark note sat mid-file after the AI features list; put it at the very bottom instead. The Platform product's five sample links were mostly changelog dates, which go stale and aren't representative docs — replace with account setup, API credentials, phone numbers, and webhooks.
…imer
The leading asterisk referenced a UI-only callout ('Migrating from
Twilio*?') that isn't part of llms.txt, so the line read as a
context-free trademark statement. Tie it to the Compatibility API
mention already in the file instead.
WireStarter and SWSH were the only two path-group links with no description, and the heading didn't distinguish the sandbox from writing your own server via the Server SDK guides. Spell out what each tool actually is.
Devon-White
marked this pull request as ready for review
September 8, 2026 18:51
hey-august
reviewed
Sep 9, 2026
hey-august
left a comment
hey-august
left a comment
Collaborator
There was a problem hiding this comment.
Review done. One real defect, otherwise the branch checks out.
Defect: the new footer sentence renders on the human landing page. fern/products/home/pages/welcome.mdx:122 puts "The documentation index for AI agents is at …" after </llms-ignore> but not inside <llms-only>. The preview HTML for /docs contains it as a visible <p> under the custom layout. Production has no such text. Wrap it in <llms-only> and add that string to the notContains list for the .md landing case in scripts/llm-export-cases.json so it can't regress.
Preview vs production llms.txt
- Served file is byte-identical to
fern/llms.txt(after host rebase). Content type staystext/plain. - Fern's auto-appended
## Instructions for AI Agentsblock is gone, including its MCP link. That link ishttps://signalwire.com/_mcp/server, which returns 404 on production today, so dropping it removes a broken pointer rather than a working one. If you want MCP advertised, it needs a working prod URL first. /docs/llms-full.txton the preview now serves the same custom file. Production 301s it. Harmless.- Platform's five sample pages swapped from changelog dates to setup pages. Intentional per the commit, but the new CLAUDE.md section calls
## Products"a manual copy of Fern's generated product list", which is no longer quite true for Platform. Tweak the wording so the next maintainer doesn't "fix" it back.
Verified
- All 141 distinct links in
fern/llms.txtreturn 200 on both preview and production. The#in-the-dashboardanchor exists on the Resources page. - All new descriptive claims (Server SDK languages, SWSH, WireStarter, Call Flow Builder, AI quickstart voice + AI Chat, REST operation slugs, etc.) trace to source pages or openapi operationIds. Product subtitles match
fern/docs.ymlexactly. yarn fern-md-checkpasses (2831 files).check-md-exports.js --list --base-url <preview>crawls all product indexes, so the rebase logic works.check-llm-exports.mjs <preview>passes 120 routes.
Nit
- "Migrate a Twilio application" is the only path section with a bare, unlinked bullet and no lead paragraph. A one-line sentence linking
/docs/compatibility-apiwould match the other sections.
Collaborator
how this text currently renders |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
llms.txtindex out of the homepage<llms-only>block into a hand-maintainedfern/llms.txt, served verbatim viaagents.llms-txtindocs.yml.## Instructions for AI Agentssection (including the MCP server link). Everything else matches production byte-for-byte apart from-vs*bullets.llms.txtinstead of the full index./docs/<product>/llms.txtindexes remain generated.scripts/llm-export-cases.jsonand repo authoring docs to match.Verification
yarn fern-check: only failure is the network-blocked FDR redirects check.yarn fern-md-check: all 2831 MDX files valid.diff <(curl -sL https://signalwire.com/docs/llms.txt | sed 's/^\* /- /') fern/llms.txt: only the removed Fern section differs.Preview checks (after the preview URL posts)
<preview>/llms.txtis the custom file with no## Instructions for AI Agents.<preview>/platform/llms.txtstill generates.node scripts/check-llm-exports.mjs <preview>andnode scripts/check-md-exports.js --base-url <preview>.Draft until the link targets in
fern/llms.txtare reviewed (follow-up pass).