fix(docs): return all valid URLs on 404 for AI agent self-correction

[michaelmagan]

Summary

• When agents guess a docs URL and 404, the markdown route (Accept: text/markdown) now returns a plain-text 404 listing every valid page plus pointers to /llms.txt, /llms-full.txt, and the .mdx suffix
• Added a custom not-found.tsx for browser visitors showing the same URL listing in HTML, grouped by section, with the docs sidebar still available

Follows up on #2697 — that PR prevented most 404s with redirects; this PR handles the ones that slip through.

Test plan

• Visit a nonexistent docs path (e.g. /concepts/doesnt-exist) in a browser — should see the new 404 page with all valid URLs
• curl -H "Accept: text/markdown" https://docs.tambo.co/concepts/doesnt-exist — should get plain-text 404 with URL listing
• Valid pages still render normally in both HTML and markdown modes

🤖 Generated with Claude Code

[pullfrog]

Reviewed PR #2698 — no actionable issues found. Both the plain-text 404 response for agents (in the .mdx route) and the HTML 404 page for browsers (in the (docs) route group) are clean and correctly scoped. Approved.

Task list (3/3 completed)

• Read PR diff and identify changed files
• Review each changed file in detail
• Self-critique comments and submit review

  ^{｜ View workflow run ｜ Triggered by Pullfrog ｜ Using Claude Opus ｜ 𝕏}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
tambo-docs	Ready	Preview, Comment	Mar 30, 2026 6:47pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
cloud	Skipped		Mar 30, 2026 6:47pm
showcase	Skipped		Mar 30, 2026 6:47pm

[pullfrog]

Clean, well-scoped PR. The plain-text 404 in the .mdx route and the HTML not-found.tsx in the (docs) group cover both the agent and browser 404 paths correctly. No issues found.

  ^{｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

TL;DR — When an AI agent (or human) hits a 404 on the docs site, the response now includes a full listing of every valid page URL so the agent can self-correct and retry with the right path. This covers both the markdown/plain-text route used by LLM agents and a new browser-facing 404 page.

Key changes

• Return a plain-text 404 with all valid URLs from the .mdx route — instead of calling notFound(), the markdown route now responds with a structured 404 body listing every documentation page plus pointers to /llms.txt and /llms-full.txt
• Add a custom not-found.tsx for browser visitors — a new 404 page rendered inside the docs layout groups all valid pages by section and links to LLM-friendly endpoints

_{Summary ｜ 2 files ｜ 1 commit ｜ base: main ← magan/docs-404-url-listing}

Plain-text 404 for agent self-correction

Before: requesting a nonexistent .mdx path triggered Next.js's default notFound(), returning an HTML error page useless to an LLM agent.
After: the route returns a text/plain 404 with the requested path, a bullet list of every valid page URL and title, and pointers to /llms.txt, /llms-full.txt, and the .mdx suffix convention.

The new build404Response helper uses source.getPages() to enumerate all documentation pages at request time, so the listing stays current without manual maintenance.

route.ts

Browser-facing 404 page with section grouping

Before: no custom 404 page existed in the docs (docs) route group — visitors saw a generic Next.js error.
After: a new not-found.tsx renders inside the docs layout with all valid pages grouped by top-level slug section, plus links to /llms.txt and /llms-full.txt for agents.

Pages are grouped into sections via a Map keyed on page.slugs[0], keeping the listing scannable for both humans and bots.

not-found.tsx

  ^{｜ View workflow run ｜ Triggered by Pullfrog ｜ Using Claude Opus ｜ 𝕏}