Renderizar las salidas
Markdown, un sitio HTML, una página autocontenida, el índice localizador para agentes y llms.txt — todo determinista, todo gratis de re-ejecutar.
handbook render --work <workdir> [--title <t>] [--html] [--html-single] [--agent-site] [--llms-txt]Sin LLM. Sin red. Determinista. Con el mismo modelo de entrada salen archivos idénticos byte a byte — así que esto pertenece a CI, en cada commit.
Las cinco salidas
Siempre se escribe.
<out>/
overview.md system prose + a mermaid stage map + "see also" links
index.md every stage, nested by depth, a paragraph each
<stage-id>.md one page per content-bearing stage
register.md the cross-stage state table (only when registers exist)La página de una etapa lleva el resumen de la etapa, enlaces a las subetapas y luego sus archivos — agrupados y ordenados como decidió la phase 2c, cada uno renderizado como una ficha de archivo: propósito, rol, ciclo de vida, hechos de llamadas y notas por función en las fichas deep.
Dos comportamientos que vale la pena conocer:
- Las páginas obsoletas se limpian. Los ids de etapa cambian entre generaciones; cada renderizado elimina primero las páginas del renderizado anterior, de modo que una etapa renombrada no deja ninguna página fantasma que el empaquetador de skills pueda recoger.
- La sección de registro por etapa es idempotente — se añade bajo un marcador, solo cuando el marcador está ausente. Volver a renderizar nunca acumula duplicados.
Enlazar a tu código fuente
handbook render --work $WORK --source-base-url https://github.com/me/repo/blob/mainCada ruta de archivo del handbook se convierte en un enlace al archivo real. Apúntalo a un
tag o a un SHA de commit en lugar de main si quieres que el handbook referencie el
código a partir del cual se generó.
Sin esta bandera la salida no contiene ninguna URL externa, que es el valor por defecto correcto para un código privado.
Títulos e idiomas
handbook render --work $WORK --title "Payments Service — Engineering Handbook"El idioma de narración se fija en el momento de la generación (--narrate-lang) y se
guarda en phase3/narration.json. El renderizador lo lee de ahí — cada etiqueta,
encabezado y cabecera de tabla se localiza para coincidir. La estructura es idéntica en
ambos idiomas, así que las herramientas que leen la salida no necesitan saber cuál de
los dos es.
Re-renderizar como hábito
Renderizar es gratis y determinista, así que intégralo en CI:
- run: handbook render --work work/api --title "API Handbook" --html --agent-site --llms-txt
- run: handbook skill --handbook work/api/handbook --out skills/api --name api \
--work work/api --source . --agent-dir work/api/handbook/agent
- run: handbook validate --skill skills/api --source .Consulta Integración en CI.
Publicar el sitio HTML
La salida es un directorio estático con enlaces relativos y sin recursos externos, así que cualquier alojamiento estático funciona:
# GitHub Pages
cp -R work/api/handbook/html/* docs-site/ && git add docs-site
# Netlify / Vercel / S3 / nginx
npx serve work/api/handbook/htmlSirve llms.txt en la raíz del sitio para que los agentes puedan encontrarlo.