Skip to content

fix(afdocs): add llms.txt directive to OpenAPI mirrors; drop mcp.json from llms.txt #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ethanj merged 1 commit into from
May 3, 2026
+19 −3
Merged

fix(afdocs): add llms.txt directive to OpenAPI mirrors; drop mcp.json from llms.txt #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion scripts/build-llms-txt.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,13 @@ export async function buildLlmsTxt({ outDir, siteUrl, siteTitle, siteTagline, do
lines.push("## Optional");
lines.push("");
lines.push(`- [skill.md](${new URL("skill.md", siteUrl).toString()}): Operating guide for agents reading these docs, when to read, how to navigate, citation conventions.`);
lines.push(`- [.well-known/mcp.json](${new URL(".well-known/mcp.json", siteUrl).toString()}): MCP server descriptor (currently local-install / stdio).`);
lines.push("");
// The MCP descriptor lives at /.well-known/mcp.json. We don't link
// it as an llms.txt entry — AFDocs treats every link in llms.txt as
// a page subject to the directive / parity / content-start checks,
// and a JSON descriptor isn't a doc page. Discovery for MCP is via
// the well-known path itself, not via llms.txt.
lines.push("MCP descriptor: /.well-known/mcp.json (not a doc page, no link).");
lines.push("");

await fs.writeFile(path.join(outDir, "llms.txt"), lines.join("\n"), "utf8");
Expand Down
14 changes: 12 additions & 2 deletions scripts/mirror-markdown.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -278,7 +278,15 @@ function renderOpenapiOperation({ doc, operation }) {
const lines = [];
lines.push(`# ${doc.title || op.summary || operation.operationId}`);
lines.push("");
lines.push(`> Machine-readable: this page mirrors OpenAPI operation \`${operation.operationId}\`.`);
// AFDocs `llms-txt-directive-md` check requires every page mirror
// to carry the same llms.txt directive blockquote that hand-authored
// pages get via the remark plugin. OpenAPI mirrors render from the
// vendored YAML, not from rendered HTML, so the directive is added
// explicitly here. Mirrors operation source separately on the next
// line for transparency.
lines.push(`> Agent index: [llms.txt](/llms.txt)`);
lines.push("");
lines.push(`Mirrors OpenAPI operation \`${operation.operationId}\` from the vendored \`atomicmemory-core\` spec.`);
lines.push("");
lines.push(`**${operation.method}** \`${operation.path}\``);
lines.push("");
Expand Down Expand Up @@ -348,7 +356,9 @@ function renderOpenapiInfo({ doc, info }) {
const lines = [];
lines.push(`# ${info.title || doc.title || "API"}`);
lines.push("");
lines.push(`> Machine-readable: this page mirrors the OpenAPI \`info\` block from the vendored spec.`);
lines.push(`> Agent index: [llms.txt](/llms.txt)`);
lines.push("");
lines.push(`Mirrors the OpenAPI \`info\` block from the vendored \`atomicmemory-core\` spec.`);
lines.push("");
if (info.version) {
lines.push(`Version: \`${info.version}\``);
Expand Down