Docs: migrar la referencia de API a Scalar, como en helmcode.com #16

Contexto

La referencia de API de nan.builders está escrita a mano (src/content/docs/api.mdx, 1148 líneas), así que se desincroniza del backend cada vez que cambia un endpoint o un modelo. En helmcode.com ya resolvimos esto con Scalar: referencia interactiva generada desde un spec OpenAPI, con tema propio y "try it" incluido. El spike lo dejó claro desde el principio: nan.builders/docs/api era el "antes" que estábamos mejorando, y el mismo enfoque se podía portar a nan después. Esto es ese después.

Objetivo: llevar la referencia de API de nan.builders a Scalar, con el mismo planteamiento y look que en helmcode.com.

Lo que ya existe en helmcode.com (repo cms, en main)

No es un spike pendiente de mergear, ya está en main y es lo que se puede portar directamente:

Documentación del proceso y de las alternativas evaluadas: SPIKE-scalar-api-reference.md en cms (branch spike/scalar-api-reference). Resumen de la decisión: Scalar es MIT y self-hosted, solo el SaaS es de pago y no lo usamos. Se descartó Redoc (try-it solo de pago) y Zudoku (no se embebe bien); Stoplight Elements queda como alternativa si algún día hace falta.

Estado actual en este repo

• Docs en content collection: src/content/docs/ (intro, getting-started, api.mdx, models.mdx, agents, apps, examples), servidos por src/pages/docs/[...slug].astro con src/layouts/Docs.astro.
• Componentes propios de docs: Callout, CodeBlock, EndpointGrid, FieldList, LimitationsCard, ModelCard, RateLimits.
• Los docs alimentan dos endpoints derivados: src/pages/api/docs/[slug].md.ts y src/pages/api/docs/manifest.json.ts, vía src/lib/mdxToText.ts, con tests (docsApi.test.ts, mdxToText.test.ts, canonicalParity.test.ts, docsSlugRoute.test.ts, docsManifestRoute.test.ts) y fixtures por componente en src/lib/__fixtures__/.
• Mismo stack que cms: Astro 6, Cloudflare Workers, Tailwind 4, i18n con astro-i18n (i18n/en.json, i18n/es.json), tokens en src/styles/tokens.css.

Decisiones a confirmar antes de implementar

1. ¿Scalar sustituye a api.mdx o convive con él? Propuesta: Scalar se queda con la referencia de endpoints y las guías escritas a mano (getting-started, examples, agents, apps, models) siguen como están. Es lo que hicimos en helmcode.
2. Los endpoints derivados de los docs. Si api.mdx sale de la colección, api/docs/[slug].md.ts y api/docs/manifest.json.ts pierden la referencia de API en su salida, que es justamente el contenido más útil para pegarle a un LLM. Hay que decidir si el manifest pasa a incluir el spec (o un Markdown generado desde él) y actualizar los tests, que hoy cubren ese contrato.
3. Fuente del spec. No hay OpenAPI propio en ningún repo: nan-cloud-api es Go/chi con rutas a mano y no genera swagger. Lo que hay es el spec crudo de LiteLLM en https://console.nan.builders/openapi.json (OpenAPI 3.1, 533 paths, servers: [], CORS abierto), que incluye toda la superficie de administración. Opciones: (a) copiar public/openapi.json de cms y re-brandearlo a nan, (b) build step que baje el spec de LiteLLM, filtre a la superficie pública y reescriba info/servers. Propuesta: (a) para salir rápido, con (b) como seguimiento aparte. Ojo con (a): ese spec se hizo por ingeniería inversa de los propios docs de nan, así que hay que validarlo contra el backend.
4. Diferencias de catálogo entre nan y helmcode. El spec de cms se escribió con la superficie de nan pero la validación se hizo contra helmcode, que no tiene todos los modelos. Hay que revisar glm5.2, mimo-v2.5 y flux-2-klein contra el /v1/models real de nan antes de publicar.
5. i18n. En helmcode el contenido del spec se queda en inglés (convención de referencias de API) y solo se localizan el shell y las etiquetas de UI de Scalar vía su opción locale. Hay que decidir si en nan hacemos lo mismo y si hace falta una ruta /es/docs/api, porque hoy los docs de nan no tienen versión en español aunque el schema de la colección tenga campo locale.
6. Indexación. En cms la página va con noindex, nofollow porque no graduó a la navegación. En nan la referencia es pública y ya se indexa, así que debería ir sin noindex y entrar en src/pages/sitemap.xml.ts.
7. Extras. ¿Portamos CopyPageButton (exporta la referencia como Markdown pegable en un LLM, encaja bien con el manifest que nan ya tiene) y el ApiAssistant? Propuesta: portar solo el botón de copiar; el asistente está parked en helmcode y arrastra proxy, secreto y rate limiting.
8. Tema. Reusar scalar-theme.css de cms, pero mapeándolo a los tokens de nan (src/styles/tokens.css). En helmcode ese cableado a tokens quedó pendiente, así que aquí conviene hacerlo bien desde el principio en lugar de heredar los hex sueltos.

Subtareas

• Confirmar las 8 decisiones de arriba
• Añadir @scalar/api-reference (no @scalar/astro, ver gotchas)
• public/openapi.json para nan: superficie pública, info y servers apuntando a la API de nan
• Validar endpoints, schemas y nombres de modelo contra el backend real de nan
• Portar ApiReference.astro adaptado al shell y la navegación de docs de nan
• Ruta /docs/api con Scalar (y /es/docs/api si aplica la decisión 5)
• scalar-theme.css mapeado a src/styles/tokens.css
• Resolver qué pasa con api.mdx y con los endpoints/tests derivados de los docs
• Enlazar la referencia desde la navegación de Docs.astro y desde el sitemap
• Verificar el build de producción en Cloudflare Workers, no solo astro dev
• Comprobar "try it" contra la API real con una key de prueba

Gotchas ya conocidos (del spike, para no repetirlos)

• Usar @scalar/api-reference, no @scalar/astro. El paquete de Astro declara peer astro@^4 || ^5 y este repo va con Astro 6, así que no instala. Con el paquete agnóstico se monta llamando a createApiReference().
• Hay que importar @scalar/api-reference/style.css a mano. Bundleado con Vite, createApiReference() no inyecta su CSS y la referencia sale sin estilos (SVGs gigantes, nav como lista de bullets).
• Modo oscuro: forceDarkModeState: 'dark' tipado as const.
• Sidebar: quitar cualquier height: 100vh del contenedor, atrapa el scroll de Scalar.
• View transitions: si se usa ClientRouter, re-montar en astro:before-swap / astro:page-load, si no la referencia solo aparece tras refrescar.
• El gotcha de npm install --ignore-scripts del spike es específico de cms (build nativo de better-sqlite3), aquí no aplica.

Criterios de aceptación

• /docs/api sirve la referencia con Scalar, con el tema de nan y el "try it" funcionando contra la API real.
• La referencia sale del spec, no de Markdown escrito a mano, de modo que actualizar un endpoint es actualizar el spec.
• Ningún modelo ni endpoint documentado que no exista de verdad en el backend de nan.
• Los endpoints api/docs/manifest.json y api/docs/[slug].md siguen coherentes, con sus tests en verde.
• El build de producción en Workers incluye Scalar y la página carga sin flash negro.