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

[ethanj]

Round 3 of AFDocs fixes — directive coverage

Overview

Real AFDocs scorecard against the live site (after PR #5) shows 93/100 (A) with 4 remaining issues. This PR clears the 2 directive-coverage warnings — quick wins that close low-hanging gaps. The other 2 (content-start-position, markdown-content-parity residual, content-negotiation) need deeper work and are explicitly out of scope below.

Check	Before	This PR
llms-txt-directive-md	WARN 28/49 (21 missing)	All mirrors now have the directive
llms-txt-directive-html	WARN 49/50 (1 missing)	False positive removed (mcp.json was treated as a doc page)
content-start-position	FAIL 16/50, worst 69%	Out of scope — DOM swizzle
markdown-content-parity	FAIL 9/49, avg 6%	Out of scope — residual is code-block whitespace
content-negotiation	FAIL	Out of scope — F1 hosting migration

Changes

Add directive to OpenAPI mirrors

scripts/mirror-markdown.mjs — renderOpenapiOperation and renderOpenapiInfo now emit > Agent index: [llms.txt](/llms.txt) as the first blockquote (same wording the remark plugin injects on hand-authored pages). The "this page mirrors operation X" note moves to a regular paragraph below.

OpenAPI .md mirrors render from the vendored YAML, so the remark plugin's directive injection (which runs on MDX) never reached them. ~30 API operation pages plus the rolled-up info page were missing the directive in their .md form.

Drop .well-known/mcp.json from llms.txt

scripts/build-llms-txt.mjs — the "Optional" section listed .well-known/mcp.json as a markdown link, so AFDocs walked it as a doc page and flagged it for missing the HTML directive. Now a non-link prose line in llms.txt mentions the descriptor exists; agents that care will look at the well-known path directly.

Out of scope

content-start-position (16/50, worst 69%)

Almost entirely OpenAPI reference pages. Diagnosis:

DOM order:
  <nav>     at  3818  (navbar)
  <aside>   at  7889  (sidebar — lists ALL ~30 API operations)
  <main>    at 14569
  <article> at 14724  (page body)

For short operation pages (e.g. GET /v1/memories/{id}) the sidebar's text content outweighs the article body, so the first meaningful content element lands past 50% in the converted text.

Fix requires a Docusaurus theme swizzle of the docs layout to render <article> before <aside> in DOM, with CSS preserving visual sidebar-on-left layout. That's a separate, larger change touching theme components.

markdown-content-parity (9/49, avg 6%, max 42%)

PR #5 already brought avg 13% → 6% by switching to HTML→md rendering with cheerio + turndown + GFM. The residual gap is dominated by whitespace tokenization in code blocks (turndown joins Prism .token-line children with \n but inline tokens don't always have spaces between them, so word-level diff over-counts gaps).

Further wins from here need either turndown rule tuning per code-language, or theme-level data-markdown-ignore attributes on elements that exist only in HTML. Bigger investment than the round-3 directive fixes.

content-negotiation (FAIL)

GH Pages cannot honor Accept: text/markdown. F1 follow-up: migrate hosting to Cloudflare Pages / Vercel / Netlify with an edge function for the rewrite.

Verification

• npm run build clean
• npm run typecheck clean
• All 4 AFDocs static artifacts present
• 7/7 platform pages + 31/31 API ref pages + 1 home page have the directive in HTML
• All 31 API ref .md mirrors now lead with > Agent index: [llms.txt](/llms.txt)
• llms.txt "Optional" section no longer links .well-known/mcp.json

🤖 Generated with Claude Code