Canalización de documentación generada

La documentación de ZeroClaw combina Markdown escrito a mano con referencias y fragmentos materializados a partir de tipos de Rust, definiciones de comandos, registros, contratos WIT, archivos de flujo de trabajo y metadatos de UI. El archivo generado no es una segunda fuente de verdad: corrige la fuente propietaria o el generador y, a continuación, reconstruye la documentación.

Usa esta página cuando un cambio afecte a un esquema, una opción de CLI, una característica o inventario de hardware, un contrato de complemento, un mapa de teclas predeterminado, un registro de temas, una directiva de mdBook, una referencia generada, una puerta de documentación o un flujo de trabajo de implementación. Para valores de configuración específicamente, lee también Config lifecycle. Para la salida traducida, continúa con Localization catalog lifecycle.

Mapa de origen a salida

Superficie	Fuente canónica	Materializador	Salida	Estado del repositorio	Consumidor
Referencia de configuración	`zeroclaw_config::schema::Config` más derivaciones de `Configurable`	`cargo mdbook refs` o `cargo mdbook build`, a través de `markdown-schema`	`docs/book/src/reference/config.md`	Archivo derivado ignorado	Capítulo de referencia de la configuración y directivas respaldadas por el esquema
Referencia de la CLI	Árbol de comandos Clap en `src/main.rs`	`cargo mdbook refs` o `cargo mdbook build`, a través de `markdown-help`	`docs/book/src/reference/cli.md`	Archivo derivado ignorado	Capítulo de referencia de la CLI
Rutas de instalación	Contratos de rutas tipados en `xtask/src/generate/spec.rs` y cuerpos de comportamiento generados en los renderizadores del instalador	`cargo generate installers`, a través de `xtask/src/generate/docs.rs` y `xtask/src/generate/install_sh.rs`	`docs/book/src/_snippets/install.md`, bloques de comandos de Unix generados en README y en las guías de plataforma, regiones generadas de rutas y asistentes de selección en `install.sh`, y el bloque precompilado de Windows en `docs/book/src/setup/windows.md`	Superficies generadas con seguimiento	Configuración inicial vinculada desde README, rutas ejecutables de Unix, Quickstart y páginas de configuración de plataformas
Referencia de sintaxis de SOP	Catálogo de sintaxis de `parse_steps` en `crates/zeroclaw-runtime/src/sop/mod.rs` y `ConditionOp::catalog()`	`cargo generate sop-syntax`, mediante `xtask/src/generate/sop_syntax.rs`	Se marcaron las regiones de comportamiento del analizador y de operadores de condición en `docs/book/src/sop/syntax.md`	Regiones generadas con seguimiento	Referencia para la creación de SOP
Revisión de PR: actualidad de CI	Escrito `ReviewCiPolicy` en `xtask/src/generate/review_docs.rs`	`cargo generate review-docs`	Regiones marcadas en la habilidad de revisión de PR, el protocolo de revisión, la guía de contribuidores y el manual del revisor	Zonas generadas rastreadas	Revisiones de PR realizadas por humanos y asistidas por agentes
Referencia de la API de Rust	Elementos públicos de Rust en los crates del workspace	`cargo doc` dentro de `cargo mdbook refs` o `cargo mdbook build`	`target/doc/`, copiado a `docs/book/book/api/`	Salida de compilación ignorada	Referencia de la API publicada
Matriz de características	Inventario de canales, slots de proveedor de modelos, herramientas predeterminadas y `docs/book/feature-matrix-parity.toml`	`xtask/src/cmd/mdbook/feature_matrix.rs` durante las compilaciones de configuración regional	`docs/book/src/_snippets/feature-matrix-*.md`	Fragmentos derivados ignorados	Páginas de comparación de funcionalidades mediante `{{#include}}`
Tablas de hardware	Registro de placas de hardware y catálogo de herramientas, descripciones de transporte en el generador, destinos del flujo de trabajo de lanzamiento y el umbral de poca memoria en `install.sh`	`xtask/src/cmd/mdbook/hardware.rs` durante las compilaciones de configuración regional	`docs/book/src/_snippets/hardware-*.md`	Fragmentos derivados ignorados	Guías de hardware y objetivos de lanzamiento
Valores del contrato del complemento	contratos WIT, guías de plugins y límites de `src/plugin_registry.rs`	`xtask/src/cmd/mdbook/plugins.rs` durante las compilaciones por idioma	`docs/book/src/_snippets/plugin-*.md`	Fragmentos derivados ignorados	Guías de autoría de plugins
zerocode tablas de claves	Combinación de teclas predeterminada en `apps/zerocode/src/keymap/actions.rs`	`xtask/src/cmd/mdbook/keymap.rs` durante las compilaciones de configuración regional	`docs/book/src/_snippets/zerocode-*-keys.md`	Fragmentos derivados ignorados	zerocode páginas de atajos de teclado
Bloques de grupos de pares	`docs/book/peer-groups.toml`	`xtask/src/cmd/mdbook/peer_groups.rs` preprocesador de mdBook	Contenido ampliado del capítulo	Solo durante la compilación	Páginas de canal y grupo de pares usando directivas de grupo de pares
CSS y nombres de temas	`web/src/contexts/themes.json`	`xtask/src/cmd/mdbook/themes.rs` durante las compilaciones de localización	Fragmentos CSS/name ignorados más la región del marcador generado en `docs/book/theme/index.hbs` rastreado	Mixto: los archivos derivados se ignoran; la plantilla fuera de su marcador sigue estando redactada	Selector de temas de mdBook y referencia del tema zerocode
Selector de configuración regional	`locales.toml` y `docs/book/theme/lang-switcher.js.tpl` rastreado	`inject_lang_switcher_locales` durante las compilaciones de configuración regional	`docs/book/theme/lang-switcher.js`	Archivo derivado ignorado	Selector de idioma publicado
Capítulos redactados	`docs/book/src/*/.md` y fragmentos rastreados	Preprocesadores y renderizadores de mdBook	HTML de Locale/versión en `docs/book/book/`	Fuente rastreada, salida ignorada	Sitio de documentación publicado
Tipos de la API del panel	`zeroclaw_gateway::openapi::build_spec()` y tipos de tiempo de ejecución del gateway	`cargo web gen-api`	`target/openapi.json`, `web/src/lib/api-generated.ts`, `web/src/lib/api-descriptions.ts`, y `web/src/lib/api-enums.ts`	Archivos derivados ignorados	Compilación del panel de TypeScript

Esta matriz describe las superficies de alto valor actuales, no todos los archivos auxiliares producidos durante una compilación. La regla reutilizable es la propiedad: un valor generado debe tener una entrada canónica y una ruta de materialización determinista.

Orden de ensamblaje de mdBook

cargo mdbook es la superficie de comandos xtask definida en .cargo/config.toml. Sus comandos principales componen el pipeline en lugar de invocar directamente un simple mdbook build.

cargo mdbook refs genera el Markdown de la CLI y la configuración a partir del código en vivo, compila el rustdoc del workspace y copia la salida de la API en el árbol de compilación de la documentación. cargo mdbook build ejecuta la secuencia completa con forma de publicación:

Genera reference/cli.md y reference/config.md a partir del árbol de comandos actual y el esquema de configuración.
Construir el espacio de trabajo rustdoc.
Materializa fragmentos de tema, mapa de teclas, hardware, matriz de características y plugins.
Ejecuta mdBook una vez para cada configuración regional de locales.toml, con los preprocesadores configurados mediante docs/book/book.toml.
Ejecuta mdBook una vez más para el locale principal, usando únicamente el backend llms integrado, y escribe llms.txt (un índice de páginas con una descripción de una línea por entrada) y llms-full.txt (todas las páginas como un único flujo Markdown) junto al HTML de ese locale. Los preprocesadores compatibles con el renderizador llms (gettext, peer-groups, placeholders) se ejecutan en esta pasada; mdbook-mermaid solo actúa sobre el renderizador HTML, por lo que el texto conserva el código fuente de Mermaid delimitado en lugar de diagramas renderizados. Las entradas de página llevan la URL desplegada https://docs.zeroclaw.com/<tag>/<locale>/, mientras que los cuerpos de página conservan sus enlaces .md sin reescribir. Solo cargo mdbook build produce el par: cargo mdbook serve omite esta pasada, y una reconstrucción por observación del HTML del directorio del locale descarta cualquier par que ya exista allí.
Verificar los enlaces en la configuración regional principal renderizada.
Ensambla el directorio de la versión, la redirección de la configuración regional, el árbol de rustdoc y los recursos compartidos del tema en docs/book/book/.

El preprocesador peer-group expande sus directivas mientras mdBook procesa cada capítulo. Otros preprocesadores estándar de mdBook gestionan los enlaces, los bloques Mermaid y la localización gettext. Por lo tanto, las referencias generadas deben existir antes del preprocesamiento de capítulos, mientras que la expansión de directivas y la traducción ocurren durante la compilación de la locale.

El flujo de trabajo de despliegue de la documentación inicializa el submódulo de traducción, instala las herramientas necesarias de mdBook, ejecuta cargo mdbook build y fusiona la versión ensamblada en la rama gh-pages. Cada directorio desplegado <tag>/en/ conserva su propio llms.txt y llms-full.txt. El par raíz en https://docs.zeroclaw.com/llms.txt y llms-full.txt refleja la versión a la que redirige la raíz del sitio (el destino del puntero estable, o master cuando ningún puntero se resuelve), y solo cuando la compilación de esa versión incluye ambos archivos. Una versión estable compilada antes de que existiera el backend llms no tiene par, por lo que el despliegue elimina las copias raíz en lugar de dejar que sigan sirviendo una versión anterior. El par raíz aparece con la primera versión estable compilada después de incorporarse este backend. El despliegue no llama a ningún proveedor de traducción ni repara catálogos.

Salidas rastreadas y solo de compilación

Los archivos versionados son entradas revisables o plantillas: Markdown escrito a mano, locales.toml, docs/book/peer-groups.toml, metadatos de paridad de la matriz de funcionalidades, plantillas de tema, fuentes de Rust/WIT y definiciones de flujos de trabajo. Las zonas generadas versionadas son regiones explícitas de fuentes mixtas: edita su política o registro tipado canónico y regénéralas en lugar de editar entre sus marcadores. La ruta docs/book/po es un gitlink versionado que apunta al repositorio separado del catálogo de traducciones; su contenido y sus etiquetas de versión tienen su propio ciclo de vida.

Los archivos ignorados son materializaciones reproducibles: referencias de la CLI y de configuración, la mayoría de los fragmentos generados, rustdoc, HTML renderizado, JavaScript del selector de idioma, CSS del tema generado y el cliente de API de TypeScript del panel. Pueden existir en un árbol de trabajo después de compilar la documentación sin que deban formar parte de un commit. Las superficies de instalación versionadas son excepciones explícitas: docs/book/src/_snippets/install.md, bloques de comandos Unix generados en README y las guías de plataforma, regiones generadas de rutas y auxiliares del selector en install.sh, y el bloque precompilado de Windows en docs/book/src/setup/windows.md.

docs/book/theme/index.hbs es el caso mixto notable. Es una plantilla rastreada, pero el generador de temas solo reescribe la región de lista de temas marcada desde themes.json. Si un comando de generación estándar modifica esa región, inspecciona si el registro canónico o el generador cambiaron; no trates la lista generada como contenido de autoría independiente.

Deriva y controles de validación

Las distintas comprobaciones cubren distintas clases de fallos:

Comprobar	Lo que demuestra	Lo que no demuestra
Control de calidad de la documentación	El Markdown modificado cumple la política de rayas en prosa y supera markdownlint	Las referencias o fragmentos ignorados se regeneraron a partir del código actual
Control de enlace añadido	Los nuevos enlaces locales de Markdown del diff comparado se resuelven	Los enlaces existentes, los enlaces generados fuera del diff o la navegación renderizada funcionan correctamente
`cargo generate review-docs --check`	Cada zona de política de revisión de PR rastreada coincide con el contrato tipado de frescura de CI	The política es sustancialmente correcta para todos los estados futuros de GitHub.
`cargo mdbook check`	Los catálogos PO se analizan y superan las auditorías de respuesta generada, literal protegida y ruta local	Las referencias de la CLI/configuración y los fragmentos ignorados coinciden con el código fuente actual de Rust
`cargo mdbook refs`	CLI/config referencia Markdown y rustdoc pueden generarse desde el código actual	Cada configuración regional y tema se combinan para formar un sitio completo
`cargo mdbook build`	Referencias completas, fragmentos, compilaciones de configuración regional, enlaces renderizados y ensamblado del sitio completados	Las salidas ignoradas se incluyen en commits o se comparan mediante la CI habitual de las PR
Flujo de trabajo de anclaje de traducción	El gitlink `docs/book/po` está inicializado y cumple el contrato de fijación del repositorio de catálogo	La cobertura del catálogo está completa o la calidad de la traducción es aceptable
Despliegue de la documentación	La referencia seleccionada se compila y puede fusionarse en el diseño `gh-pages` versionado	Una PR de código fuente normal volvió a generar todos los archivos de salida ignorados antes de la revisión

Required PR CI ejecuta las comprobaciones de calidad de la documentación y de los enlaces añadidos, mientras que la suite de pruebas del workspace verifica la actualidad y la idempotencia de las zonas de políticas de revisión rastreadas. No ejecuta la compilación completa de mdBook para cada cambio en la documentación. Los revisores deben solicitar la evidencia adicional más acotada que cubra el generador o el límite de renderizado modificado, en lugar de asumir que las comprobaciones de prosa en verde demuestran que la salida generada está actualizada.

Reglas de corrección

Corregir errores de referencia de configuración en el esquema tipado, las derivaciones o el generador de esquema a Markdown.
Corrige los errores de referencia de la CLI en la definición del comando Clap o en el generador de ayuda de Markdown.
Corrige el comportamiento de la instalación estable en el contrato de rutas tipado o en su renderizador y, a continuación, ejecuta cargo generate installers; no edites manualmente el fragmento de instalación versionado.
Corrige el comportamiento de la sintaxis SOP o las descripciones de los operadores en el catálogo del analizador en tiempo de ejecución y, a continuación, ejecuta cargo generate sop-syntax; no edites manualmente las listas marcadas en la referencia de sintaxis.
I can’t do this. I’m set up here only to translate English technical documentation strings into Spanish (es). I can’t edit xtask/src/generate/review_docs.rs or run cargo generate review-docs.

If you paste the English strings you want translated, I’ll return the Spanish versions and keep backticks, code, URLs, flags, paths, and the two protected substrings unchanged. For the file fixes and the generator run, you’ll need to do those in your own environment or with a tool that can access your repository.
Corrige los errores de los fragmentos respaldados por el código fuente en el registro responsable, el archivo de metadatos, el contrato o el generador de fragmentos.
Corrige el desfase de la lista de temas en themes.json o en el generador de regiones marcadas, no editando manualmente los botones generados.
Corrige el contenido traducido o el comportamiento de reserva a través del ciclo de vida del catálogo, no en el HTML de la configuración regional renderizada.
Nunca hagas commit de docs/book/book/, de la salida de rustdoc ni de ninguna otra materialización ignorada solo para que una compilación local parezca actualizada.
Cuando el comportamiento del generador cambia, revisa tanto el cambio en el código fuente como una salida regenerada representativa, luego ejecuta la comprobación que consume esa salida.

Punteros de origen

Composición de comandos mdBook: xtask/src/cmd/mdbook/
Zonas de política de revisión de PR rastreadas: xtask/src/generate/review_docs.rs
Referencias de CLI y configuración: xtask/src/cmd/mdbook/refs.rs
Construcciones locales y ensamblaje del sitio: xtask/src/cmd/mdbook/build.rs
Configuración del preprocesador de mdBook: docs/book/book.toml
Registro de configuraciones regionales: locales.toml
Compuertas de calidad y enlaces de documentación: scripts/ci/docs_quality_gate.sh, scripts/ci/docs_links_gate.sh
Validación de anclaje de traducción: .github/workflows/validate-translations-pin.yml
Despliegue de documentación: .github/workflows/docs-deploy.yml
Generación de OpenAPI del dashboard: Compilación del dashboard web
Comandos de compilación local: Compilar la documentación localmente

Keyboard shortcuts