Contribuir a esta documentacion

Esta documentacion crece junto al producto. Cada cambio que afecta a clientes, integradores o operadores se documenta aqui en el mismo PR que introduce el cambio. Sin excepcion.

Regla operativa

Cada PR que toca contrato publico (endpoint API, funcion del SDK, setting visible del panel, comportamiento user-facing) debe incluir el update correspondiente de packages/docs/content/ en el mismo PR. Es parte del Definition of Done.

Esta pagina explica como hacerlo bien y que herramientas usar.

Como se ve

Antes de entrar en reglas, aqui tienes ejemplos vivos de los componentes que esta misma seccion documenta. Las capturas son del propio sitio docs.mibizum.io en produccion.

Home de docs.mibizum.io - estetica developer-docs en modo oscuro

Una pagina de guia: sidebar jerarquico, contenido central, tabla de contenidos a la derecha

1. Landing

El home presenta el producto en 3 ejes. Hero + 6 features + quickstart inline.

Paso 1 de 4

Cuando hay que actualizar la doc

Tipo de cambio	Doc a actualizar
Endpoint REST nuevo, modificado o eliminado	/api/<recurso> + nav
Funcion nueva o cambio de signatura en SDK	/sdk/<area>
Setting nuevo del panel	/quickstart/conceptos + pagina del feature
Concepto nuevo del producto	/quickstart/conceptos + /resources/glossary
Codigo de error nuevo o renombrado	/api/errors + /resources/errors si afecta UX
Cambio breaking del API	/resources/changelog con seccion Breaking
Leccion aprendida en hotfix relevante a merchants	/guides/<slug> (manual o via script de sync)
Refactor interno sin cambio de contrato	No requiere doc
Bug fix que devuelve el comportamiento previamente documentado	No requiere doc (si el bug estaba documentado, quitar)

En duda, documenta. Es mas barato escribir un parrafo de mas que dejar deuda silenciosa.

Herramientas disponibles

<Screenshot>

Componente Vue para insertar capturas con sombra, borde redondeado y zoom al hacer click. Ya esta registrado globalmente en el tema, no hace falta import.

<Screenshot
  src="/screenshots/panel-aprendizaje.png"
  alt="Panel de Aprende del cliente con sugerencias IA"
  caption="La pestaña Aprende del cliente muestra las sugerencias del aprendizaje IA pendientes de revision."
/>

Las imagenes viven en packages/docs/content/public/screenshots/. Se referencian con path absoluto desde la raiz del sitio (/screenshots/...).

<TourCarousel>

Componente Vue para secuencias multi-paso con prev/next y contador. Pensado para feature-shows y onboardings. Navegacion por teclado (flechas).

<TourCarousel
  :steps="[
    {
      src:   '/screenshots/onboarding-1.png',
      alt:   'Crea tu tenant',
      title: '1. Crea tu tenant',
      body:  'Elige un slug que identifique tu instancia. No se puede cambiar despues.'
    },
    {
      src:   '/screenshots/onboarding-2.png',
      alt:   'Carga tu primer catalogo',
      title: '2. Carga tu primer catalogo',
      body:  'Sube los items via API REST o instala el adapter de tu plataforma.'
    },
    {
      src:   '/screenshots/onboarding-3.png',
      alt:   'Configura el widget',
      title: '3. Configura el widget',
      body:  'Pega el script tag en tu tienda y el buscador se autoinstala.'
    }
  ]"
/>

¿Carousel o secuencia estatica?

• Carousel (<TourCarousel>): mejor para mostrar features completas en pocas pantallas. Pulido. Bueno para landings.
• Secuencia estatica (varios <Screenshot> en linea con texto entre cada uno): mejor para guias tecnicas paso-a-paso. Mas legible para imprimir o ctrl+F. Recomendado por defecto en /guides/ y /quickstart/.

Ejemplo de secuencia estatica:

### 1. Crea tu tenant

<Screenshot src="/screenshots/paso-1.png" alt="..." caption="..." />

Texto que explica el paso 1.

### 2. Carga tu catalogo

<Screenshot src="/screenshots/paso-2.png" alt="..." caption="..." />

Texto que explica el paso 2.

Containers de callout

VitePress soporta nativamente:

::: tip Titulo opcional
Para informacion adicional util.
:::

::: warning
Para algo que el lector tiene que tener en cuenta.
:::

::: danger
Para errores graves o anti-patrones criticos.
:::

::: info
Para datos neutros.
:::

Scripts automaticos

infra/scripts/sync-kb-from-buscador.sh

Sincroniza lecciones del Knowledge Base interno del repo buscador al sitio publico. Cada leccion del KB tiene un flag publish_to_public_docs en su frontmatter:

• true → el script la copia a /guides/. Usalo cuando la leccion sea relevante a merchants y este escrita en tono user-facing.
• false → el script la salta. Usalo cuando sea developer-only o cuando exista version publica reescrita a mano.

# Ver que cambios pendientes hay sin aplicar
./infra/scripts/sync-kb-from-buscador.sh --dry-run --verbose

# Aplicar cambios
./infra/scripts/sync-kb-from-buscador.sh

# Apuntar a otro path del repo buscador si esta en otro sitio
BUSCADOR_REPO=/path/al/buscador ./infra/scripts/sync-kb-from-buscador.sh

infra/scripts/generate-changelog.sh

Genera un bloque markdown para resources/changelog.md desde los conventional commits del rango indicado. No modifica el fichero por su cuenta - emite el bloque a stdout. Klein lo edita despues para anadir contexto humano.

# Desde el ultimo tag
./infra/scripts/generate-changelog.sh

# Desde una fecha
./infra/scripts/generate-changelog.sh 2026-05-01

# Desde el penultimo merge (util tras cerrar un sprint largo)
./infra/scripts/generate-changelog.sh --since-last-merge

# Desde un SHA o tag concreto
./infra/scripts/generate-changelog.sh v1.2.0

Las reglas de clasificacion siguen Conventional Commits:

Tipo de commit	Seccion del changelog
feat(...)	Added
fix(...)	Fixed
perf(...), refactor(...)	Changed
feat(...)! o BREAKING CHANGE: en body	Breaking (ademas de su seccion)
`docs	test

Capturas: de donde sacarlas

Las capturas del panel admin que aparecen en la doc vienen del tenant demo publico (mibizum.io/login con la cuenta demo, ver /quickstart para credenciales). El tenant demo tiene un catalogo ficticio neutro y datos generados para que las capturas sean fieles al producto real sin exponer informacion de comercios reales.

No uses capturas con datos reales de comercios

Si una captura muestra emails, queries con nombres de cliente, IPs, ordenes o cualquier dato PII de un merchant real, el cambio se rechaza en review. Usa siempre el tenant demo o ofusca con script.

Estilo

• Espanol en todo el copy (lengua de trabajo del producto).
• Hyphen-minus ASCII - como guion, nunca — ni –. Si una aposicion envolvente lo pide, usa (parentesis).
• No nombres tecnologias de terceros en copy publico: motor de busqueda en lugar de su nombre comercial; aprendizaje IA / Smart Mibizum en lugar del modelo concreto.
• Concision sobre exhaustividad: una pagina debe poder leerse de un tiron. Si crece mucho, divide en sub-paginas.
• Ejemplos reales con numeros: "en una tienda de N items, X queries devolvian 0" es 10 veces mas util que "puede haber muchas queries sin resultados".
• Anti-patrones documentados: tras la regla, anade un bloque "Como NO hacerlo" con el caso real que se intento y por que falla.

Para Klein-futuro

Esta seccion es para el siguiente agente que cierre un sprint:

1. Al cerrar el sprint del buscador: ejecuta sync-kb-from-buscador.sh si has anadido lecciones al KB.
2. Al cerrar el sprint de mibizum: si has cambiado contrato publico, verifica que el PR incluye los .md correspondientes. Si has anadido un feature visible, captura del tenant demo + embebe en la doc del feature.
3. Antes de mergear un sprint con varios fix/feat, ejecuta generate-changelog.sh --since-last-merge y anade el bloque editado a resources/changelog.md.
4. Verifica el build: npm -w @mibizum/docs run build debe pasar sin warnings nuevos. Si rompe, arregla antes de mergear (el build-check.yml de CI lo enforcement, pero mejor pillarlo local).