Mantener esta documentación

Dónde vive

Es el sitio apps/docs del Monorepo, hecho con Astro y Starlight. Cada página es un archivo Markdown en apps/docs/src/content/docs/, y la carpeta decide la sección del menú:

Carpeta	Sección
`empezar/`	Empezar
`pantallas/`	Pantallas
`configuraciones/`	Configuraciones
`desarrolladores/`	Desarrolladores
`referencia/`	Referencia

El orden dentro de cada sección lo da sidebar.order en el encabezado de la página. Se escribe a mano: no se genera desde otra documentación.

Cómo se escribe una página de pantalla

Cada pantalla sigue la misma forma, para que se lea igual en todas:

Para qué sirve: una o dos frases.
Qué se ve.
Qué se puede hacer: las acciones, con el nombre del botón tal como aparece en Boost.
Quién puede: en palabras, no con nombres técnicos de permisos.
Se configura en: el enlace a su sección de Configuraciones.

Cada función que se describe se verifica en el código de la pantalla. Si un botón existe pero todavía no hace nada, no se documenta como si funcionara.

Qué no puede aparecer

Direcciones de API ni rutas del backend.
Secretos: contraseñas, llaves, tokens, encabezados de autorización ni detalles de cómo se guarda la sesión.
Datos de clientes: nombres de empresas cliente, teléfonos, correos o capturas con datos reales.
Historia interna del proyecto (qué se movió de dónde, planes de migración): aquí se describe lo que existe hoy.

El build de este sitio corre antes una revisión que busca todo eso y falla si lo encuentra, en vez de publicar. La misma revisión comprueba que los enlaces internos lleven a páginas que existen.

Comandos

npm run docs:dev        # el sitio en la computadora, con recarga
npm run docs:validate   # solo la revisión (contenido prohibido y enlaces)
npm run docs:build      # revisión + build, lo mismo que corre en CI

Para modelos de lenguaje

El sitio genera solo, a partir de las mismas páginas, /llms.txt (el índice), /llms-full.txt (todo el texto) y la versión .md de cada página. No hay que mantenerlos a mano.

Códigos de error

La sección Códigos de error es la única que no se escribe a mano: sale del catálogo de errores de BoostAPI, que se arma leyendo el código del backend y la descripción que el equipo escribe junto a cada código. Aquí se guarda una copia pública de ese catálogo en apps/docs/src/data/errores/catalogo.json, y de ella salen el índice, una página por familia (src/pages/codigos-de-error/), su versión en Markdown y el buscador.

Cuándo sincronizar: cada vez que BoostAPI cambia su catálogo (un código nuevo, uno que cambia de significado o de estado, uno que se retira). En BoostAPI, su chequeo del catálogo falla mientras un código no esté documentado, así que lo que llega aquí ya viene descrito.

# desde apps/docs, con BoostAPI clonado al lado del Monorepo (../BoostAPI)
npm run errores:check                          # ¿la copia está al día? (no escribe)
npm run errores:sync                           # copia desde la copia de trabajo de BoostAPI
npm run errores:sync -- --ref upstream/main    # o desde una rama (tras git fetch en BoostAPI)
npm run errores:sync -- --desde /ruta/a/BoostAPI --detalle
npm run build                                  # el guardia también revisa la copia

Si BoostAPI está en otro lugar, se pasa --desde o se define BOOSTAPI_DIR. La copia guarda en meta el commit de BoostAPI del que salió.

Qué hace la sincronización con los textos: les aplica las mismas reglas que al resto del sitio. Quita las referencias internas entre paréntesis y las oraciones con rutas de API, historia interna, nombres de clientes o encabezados de autorización. Si un texto obligatorio (el significado de un código, el título de una familia) queda vacío o todavía rompe una regla, falla y dice qué código arreglar; no publica a medias. Lo correcto es corregir el texto en BoostAPI; mientras tanto, apps/docs/scripts/errores-ajustes.json reemplaza ese texto solo aquí, y la sincronización avisa cuando un ajuste ya no se usa.

La copia se commitea junto con el cambio que la motivó. No se edita a mano: el siguiente errores:sync la reescribe.