Per @briankwest's llms.txt effectiveness audit. (source)
The audit scores the docs around 7.5/10 for AI readiness. Discovery is already strong — root and per-section llms.txt, .md exports, the docs MCP server, OpenAPI 3.1 and JSON Schema from TypeSpec. The remaining problems are semantic loss in the exports, terminology drift left over from product renames, redirects that destroy query intent, and no machine-readable guidance about which product surface to choose.
The two P0 correctness items were already filed from Brian's earlier report and are adopted here as sub-issues: #525 (.md exports strip defined terms) and #526 (broad legacy redirects). The rest of the roadmap is broken out into the remaining sub-issues.
Suggested order (the sub-issue list below is sorted to match): #525 and #526 first — everything downstream reads the exports. Then #560's line-splitting fix immediately, with its decision-map restructure following #562. Then #561 → #562 (the registry feeds the manifest) and #388. Then #563, which publishes views of #561/#562 (its MCP guide half can start anytime). Then #564, #565, #566. #567's structural gates should land as soon as #525/#526 are fixed; its retrieval and answer evals come last. #580 is last of all — it needs the site and MCP server instrumented first, and what it turns up feeds later rounds of #561, #562, and #566. Note that #525, #560, #564, and #565 depend on Fern's export pipeline, so each may be part upstream feature request rather than pure repo work.
#591 (executable-example standards) and #592 (production-readiness paths) sit outside that sequence. Both are separable from machine-readability — they're bad for humans in the same way they're bad for models — so neither blocks anything above, and both can be picked up whenever there's room. Every item in the audit is now tracked here.
Per @briankwest's llms.txt effectiveness audit. (source)
The audit scores the docs around 7.5/10 for AI readiness. Discovery is already strong — root and per-section llms.txt, .md exports, the docs MCP server, OpenAPI 3.1 and JSON Schema from TypeSpec. The remaining problems are semantic loss in the exports, terminology drift left over from product renames, redirects that destroy query intent, and no machine-readable guidance about which product surface to choose.
The two P0 correctness items were already filed from Brian's earlier report and are adopted here as sub-issues: #525 (.md exports strip defined terms) and #526 (broad legacy redirects). The rest of the roadmap is broken out into the remaining sub-issues.
Suggested order (the sub-issue list below is sorted to match): #525 and #526 first — everything downstream reads the exports. Then #560's line-splitting fix immediately, with its decision-map restructure following #562. Then #561 → #562 (the registry feeds the manifest) and #388. Then #563, which publishes views of #561/#562 (its MCP guide half can start anytime). Then #564, #565, #566. #567's structural gates should land as soon as #525/#526 are fixed; its retrieval and answer evals come last. #580 is last of all — it needs the site and MCP server instrumented first, and what it turns up feeds later rounds of #561, #562, and #566. Note that #525, #560, #564, and #565 depend on Fern's export pipeline, so each may be part upstream feature request rather than pure repo work.
#591 (executable-example standards) and #592 (production-readiness paths) sit outside that sequence. Both are separable from machine-readability — they're bad for humans in the same way they're bad for models — so neither blocks anything above, and both can be picked up whenever there's room. Every item in the audit is now tracked here.