feat(docs): MDX content collection + public sync API

[Saul-Gomez-J]

Summary

• Migrar las páginas de docs (.astro por ruta) a una content collection MDX en src/content/docs/, con un único src/pages/docs/[...slug].astro que las renderiza y un Docs.astro que arma nav, breadcrumb y prev/next leyendo la propia colección.
• Pulir la tipografía de .docs-content (h3, links, listas, blockquotes, tablas, imágenes), añadir toolbar + botón Copiar a cada <pre> de markdown y arreglar la regla de code inline (:not(pre) > code) para que los bloques Shiki no parezcan "seleccionados".
• Exponer una API pública que el bot (y cualquier cliente) puede consumir como fuente única de verdad:
  • GET /api/docs/manifest.json — índice versionado con contentHash SHA-256 y contentUrl por entrada.
  • GET /api/docs/{slug}.md — re-renderiza la página, extrae el artículo entre <!--ARTICLE-START--> / <!--ARTICLE-END--> y devuelve Markdown limpio vía lib/htmlToText.ts (sin clases, sin estilos, conservando indentación de bloques de código y entidades decodificadas una vez al final). Headers: Cache-Control, ETag, X-Content-Hash.

Por qué

Hasta ahora cada doc vivía en su propio .astro y el bot servía un set de .md distinto bajo bot/docs/knowledge/, lo que obligaba a editar dos repos para cada cambio y dejaba al bot fuera de sync. Con la colección única, la web es la fuente de verdad y la API entrega el mismo contenido en texto plano para indexar (sin ruido HTML).

Notas para revisar

• Añadir un doc nuevo = crear src/content/docs/<slug>.md|.mdx con frontmatter (title, description, order). La nav y [...slug] se actualizan solos.
• Los componentes en src/components/docs/ (ModelCard, LimitationsCard, EndpointGrid, FieldList, Callout) son lo único que necesita JSX, por eso models y api quedan en .mdx.
• El htmlToText extrae los bloques de código a placeholders (CODE_BLOCK_N) antes de colapsar whitespace y los restaura al final — así no se pierde indentación en los fenced blocks.
• En Limitations evita usar < / > dentro de strings JS de props: son literales JS, no HTML; ya quedan literales < / >.

Test plan

• npm run dev — visitar /docs, /docs/api, /docs/models, etc. y verificar nav, breadcrumb, prev/next y toolbar de Copiar.
• Comprobar curl http://localhost:4321/api/docs/manifest.json | jq — version, entries[].contentHash, contentUrl.
• Comprobar curl -i http://localhost:4321/api/docs/api.md — Content-Type: text/markdown, ETag, X-Content-Hash, sin HTML residual.
• curl /api/docs/../etc/passwd.md y similares → 400.
• curl /api/docs/no-existe.md → 404.
• npm run build sin errores.

🤖 Generated with Claude Code

[barckcode]

Gracias Saúl, dirección 100% correcta (web como source of truth + manifest con sha256 + diff selectivo en el bot). Antes de mergear y promover DOCS_USE_REMOTE=remote, tres blockers y un par de notas menores.

Blockers

1. [slug].md.ts no debe re-renderizar la página y deshacer el HTML

Hoy el endpoint hace fetch(${origin}/docs/${slug}) → SSR completo (layout, sidebar, Shiki, MDX components) → recorta entre marcadores → lo pasa por htmlToText.ts (140 LOC de regex). Y manifest.json.ts lo hace N veces en paralelo por cada hit.

Problemas concretos:

• N sub-requests SSR por hit al manifest.
• contentHash frágil: cambio en ModelCard/EndpointGrid/Shiki/atributos data-* de Astro → cambia el HTML → cambia el hash → el bot re-embedde sin cambio semántico (cuesta tokens cada vez).
• htmlToText.ts se romperá silenciosamente con cualquier cambio del runtime Astro/MDX.

Cambio propuesto: servir entry.body (el body crudo del MDX en la content collection) y procesarlo con remark + remark-mdx para convertir los componentes JSX (ModelCard, EndpointGrid, FieldList, Callout, LimitationsCard) a markdown plano vía visitor sobre los nodos mdxJsxFlowElement / mdxJsxTextElement. Cero SSR, cero parser HTML; depende solo de nuestros componentes (estable).

Esto elimina htmlToText.ts y los marcadores <!--ARTICLE-START/END--> del layout.

2. ETag se emite pero no se honra If-None-Match

Ambos endpoints generan el ETag pero no leen request.headers.get('if-none-match') → nunca devuelven 304. Patch trivial; es lo que justifica generar el hash. También mejora el shared cache en Cloudflare.

3. Falta toda la batería de tests

No se añade ningún test en una PR que introduce un parser de HTML, dos endpoints públicos y un hash que será consumido por otro servicio. Mínimo para mergear:

• lib/contentHash.ts: vacío, ASCII, UTF-8 multibyte.
• Serializer JSX→MD (lo que sustituye a htmlToText): fixture por cada componente rich + un caso compuesto.
• Endpoint manifest.json: shape del payload, ordenación por order, ETag estable para el mismo input, If-None-Match → 304.
• Endpoint [slug].md: slug inválido → 400, slug inexistente → 404, body sin HTML residual, ETag + X-Content-Hash coherentes.

Notas menores

• Manifest.version se calcula pero el bot no lo usa. O lo aprovechas como short-circuit ("si la version no cambió, no toques nada") o lo eliminas.
• manifest.json.ts no valida entry.id contra SAFE_SLUG; coherencia con [slug].md.ts.
• Cache-Control max-age=60 vs docs_refresh_interval=900 en el bot → desfase que produce cache misses sin valor. Alinear.
• El frontmatter que añade [slug].md.ts al body es ida-vuelta innecesaria (el bot ya tiene title/order/description desde el manifest y lo descarta con _strip_frontmatter). Sirve solo el body.

Lo que está bien y conviene preservar

• Migración a content collection MDX con [...slug].astro único — añadir doc = añadir fichero, nav/breadcrumb/prev-next derivados de la colección.
• Componentes ricos en src/components/docs/ extraídos limpios.
• Pulido de .docs-content (toolbar + copy, fix de :not(pre) > code).
• prerender = false correcto para que la API sea siempre fresca.