FND-002: Documentación Intencional: Estándares, Estructura y Estrategia de i18n

A partir de v0.7.0 · Tipo: Documentación · Rev. 7

Referencia canónica · Ratificada por el equipo · Rev. 7 Discusión original del RFC: #5576

Una nota para el equipo antes de que lean esto.

La documentación no es lo que escribes después de que el código está terminado. Es una superficie del producto por derecho propio, la interfaz entre el proyecto y cada persona que alguna vez contribuirá a él, lo usará o construirá sobre él. Una base de código sin documentación obliga a cada persona nueva a redescubrir todo desde cero. Una base de código con mala documentación suele ser peor, porque da a las personas una falsa confianza. Este RFC propone tratar la documentación con la misma intencionalidad que estamos aplicando a la arquitectura: primero la visión, luego la estructura y después el contenido.

Tabla de contenidos

1. La filosofía de la documentación
2. Evaluación honesta: dónde estamos hoy
3. Un marco de clasificación: Artefactos de EA en una página
4. El problema de i18n
5. La división del repositorio y la wiki
6. Estándares de ADR
7. AGENTS.md como la capa de desarrollo de IA
8. La estructura objetivo
9. El contrato de documentación de reemplazo
10. Estándares que deberíamos adoptar
11. Hoja de ruta por fases

Historial de revisiones

Política de revisión de Foundation

Los metadatos de revisión de Foundation conservan las revisiones de borrador incorporadas a la línea base ratificada y registran la evolución de las decisiones normativas posteriores a la ratificación. Incrementa la revisión mostrada y añade una fila cronológica cuando un cambio fusionado modifique la arquitectura, el proceso obligatorio, los contratos de lanzamiento, el comportamiento de los colaboradores o la titularidad de una fuente autorizada. Una reversión posterior constituye una revisión independiente porque ambos estados rigieron el proyecto de forma sucesiva. Los borradores que solo contienen incidencias y que se excluyeron de la ratificación no cuentan.

No incrementes la revisión por reubicaciones, cambios de formato, puntuación, normalización de encabezados, reparaciones de enlaces o actualizaciones de rutas que no cambien el contrato. Cuando un documento fundacional delega explícitamente los detalles operativos a otra fuente mantenida, los cambios limitados a esos detalles no revisan el documento fundacional.

Los dos valores de revisión que se muestran y la fila con la revisión local más alta del historial deben actualizarse juntos en el mismo cambio. Las filas que se añadan con una enmienda conservan la fecha de revisión asignada a esa enmienda. Cuando el historial se complete retroactivamente, utiliza la fecha en la que el cambio entró en master.

1. La filosofía de la documentación

Los problemas de documentación casi siempre provienen de omitir una pregunta que debería haberse formulado antes de escribir la primera oración: ¿qué tipo de documento es este y para quién está dirigido?

Sin una respuesta a esa pregunta, la documentación se acumula como un montón de páginas que son todas ligeramente diferentes formas de la misma categoría vaga: “cosas sobre el proyecto”. Las guías de configuración conviven con las decisiones de arquitectura. Los tutoriales para usuarios se encuentran junto con los estándares internos de codificación. Treinta traducciones al idioma del README compiten por espacio con el único documento de política de seguridad. Nadie puede encontrar nada, todo se vuelve obsoleto a un ritmo diferente, y cada PR que toca la documentación se convierte en una negociación sobre qué páginas necesitan actualizarse.

La solución no es escribir más documentación. La solución es decidir, antes de escribir nada, qué tipo de artefacto estás creando. El tipo determina el formato, la audiencia, la ubicación, el ciclo de vida y quién es responsable de mantenerlo actualizado. Una vez establecido el tipo, el resto sigue de manera natural.

Este RFC adopta el framework EA Artifacts on a Page de Svyatoslav Kotusev (https://eaonapage.com) como lente de clasificación para toda la documentación de ZeroClaw. El framework está basado en evidencia, es deliberadamente no prescriptivo y se corresponde directamente con los tipos de documentos que un proyecto de infraestructura de código abierto realmente necesita.

El principio fundamental, tomado de la filosofía de desarrollo más amplia que este equipo está adoptando:

Los documentos, al igual que el código, deben trazar una línea ascendente a través de Visión → Arquitectura → Diseño → Implementación. Si no puedes nombrar el tipo de artefacto y su audiencia antes de escribir, no estás listo para escribir.

2. Evaluación honesta: dónde estamos hoy

2.1 La huella de i18n

El problema más inmediatamente medible en la documentación actual es el sistema de localización:

El sistema i18n crea una carga tributaria para los colaboradores en cada PR de documentación. El archivo docs-contract.md actual contiene este requisito:

Si un cambio afecta la IA de los documentos, las referencias del contrato de tiempo de ejecución o la redacción visible para el usuario en los documentos compartidos, realiza el seguimiento de i18n para las locales admitidas en el mismo PR.

Esto significa que un colaborador que corrige un error tipográfico en una guía de configuración debe actualizar hasta seis versiones en diferentes idiomas de ese documento, o la solicitud de extracción (PR) no superará la revisión. Esta es una barrera significativa para la contribución, especialmente para los estudiantes y los ingenieros en etapas tempranas de su carrera, que constituyen la mayor parte de la base de colaboradores de este proyecto.

2.2 El problema de la estructura

La jerarquía actual de docs/ mezcla tres tipos de documentos fundamentalmente diferentes al mismo nivel:

• Documentos relacionados con el código que deben versionarse junto con la base de código (ADRs, especificaciones de la API, política de seguridad, proceso de contribución)
• Documentos operativos dirigidos al usuario que deben actualizarse de forma independiente de las versiones del código (guías de configuración, resolución de problemas, manuales de implementación)
• Documentos de la comunidad que deben ser mantenidos por la comunidad y no requieren un proceso formal de revisión (traducciones, preguntas frecuentes, guías de la comunidad)

Los tres residen en docs/ sin distinción estructural entre ellos. El resultado es una pila plana con un SUMMARY.md mantenido manualmente que alguien debe actualizar cada vez que ocurre algún cambio.

2.3 La brecha de ADR

Cuando se redactó este RFC, el proyecto tenía dos Architecture Decision Records en el antiguo árbol de documentación: ADR-003 para plugins WASM y ADR-004 para la propiedad del estado compartido de las herramientas. ADR-004 era un modelo especialmente sólido: bien estructurado, con referencias al código, específico. Pero el proyecto había tomado al menos cinco o seis decisiones arquitectónicas de igual o mayor trascendencia que nunca se habían registrado:

• La elección de Rust sobre TypeScript
• El modelo de extensibilidad basado en rasgos
• El diseño del sistema de plugins WASM
• El contrato de almacenamiento de memoria independiente del backend y el valor predeterminado SQLite
• El modelo de seguridad (códigos de emparejamiento, niveles de autonomía, capas de sandbox)

Sin estos registros, cada nuevo colaborador debe redescubrir el razonamiento mediante la arqueología del código. Cada asistente de codificación con IA que lee la base de código obtiene el qué, pero no el por qué. Esta es una de las formas más costosas de deuda técnica no documentada.

2.4 Qué es bueno

El concepto de docs-contract.md, tratar la documentación como una superficie de producto gobernada, es la intuición correcta. Solo necesita las reglas adecuadas. El AGENTS.md en la raíz es excelente y establece el precedente correcto para el desarrollo asistido por IA. ADR-004 demostró que el equipo podía redactar registros arquitectónicos de alta calidad.

3. Un marco de clasificación: Artefactos de EA en una página

El marco de trabajo Artefactos de EA en una Página define cinco familias de artefactos de arquitectura. Cada documento en el repositorio de ZeroClaw debe pertenecer a una de estas familias, y esa familia determina todo sobre dónde se encuentra, cómo se formatea y cuándo se vuelve obsoleto.

Lo que notablemente falta en esta tabla: guías de usuario, instrucciones de configuración, cómo-tos específicos por canal, solución de problemas y preguntas frecuentes. Estos son contenidos operativos, no artefactos de EA. No se versionan junto con el código. Deben estar en la Wiki de GitHub.

Usando el Framework

Antes de escribir cualquier documento, haz y responde estas dos preguntas:

1. ¿A qué familia de artefactos pertenece esto? Si no puedes responder a esta pregunta, no estás listo para escribir.
2. ¿Necesita versionarse junto con el código? Si es así, se incluye en el repositorio. Si no, se coloca en la Wiki.

Una prueba útil para la segunda pregunta: ¿este documento se volvería incorrecto o engañoso si alguien lo leyera en comparación con una versión diferente de la base de código? Si es así, vive en el repositorio, versionado junto con el código. Si no, vive en la Wiki.

4. El problema de i18n

4.1 El argumento para la eliminación

El caso para eliminar todo el contenido no inglés del repositorio se basa en cuatro pilares:

1. La audiencia tiene traducción bajo demanda. Los usuarios principales de ZeroClaw son personas que ejecutan un asistente de IA. Cada una de estas personas tiene acceso a traducción automática instantánea y de alta calidad, ya sea a través del agente que ejecutan, a través de su navegador o a través de cualquiera de las docenas de servicios de traducción gratuitos. El beneficio práctico de incluir traducciones en el repositorio es marginal.

2. Las traducciones están casi con seguridad desactualizadas. Es probable que el contenido traducido automáticamente se haya generado una sola vez y no se haya mantenido sincronizado con la fuente en inglés. La documentación desactualizada es peor que no tener documentación para el desarrollo asistido por IA, ya que los modelos de lenguaje derivarán conclusiones incorrectas con confianza a partir de información obsoleta.

3. El impuesto al colaborador es real y medible. El requisito de paridad de docs-contract.md significa que cada PR de documentación debe tocar hasta seis versiones de idiomas. Esto hace que las contribuciones a la documentación sean costosas y desalientan precisamente ese tipo de mejoras pequeñas e incrementales (corregir un error tipográfico, aclarar un paso, actualizar una referencia obsoleta) que mantienen la documentación en buen estado.

4. La localización es un trabajo comunitario, no una tarea del proyecto principal. Las comunidades mejor posicionadas para mantener la documentación en japonés son los colaboradores que hablan japonés. Incluir el contenido localizado en el repositorio principal con un requisito de paridad traslada la carga a los mantenedores principales en lugar de a las comunidades que se benefician de ello. La Wiki de GitHub invierte esto correctamente: los miembros de la comunidad pueden editar y mantener las páginas de su idioma sin necesidad de abrir solicitudes de extracción (PRs).

4.2 Qué se mantiene

Una cosa que vale la pena preservar: la estructura del enfoque de i18n. La idea de hacer que ZeroClaw sea accesible en múltiples idiomas es correcta. Solo la ubicación y el modelo de propiedad son incorrectos.

4.3 La estrategia de reemplazo

1. Eliminar todos los archivos README.*.md de la raíz del repositorio, excepto README.md

2. Eliminar docs/i18n/ por completo

3. Eliminar todos los archivos del hub que no estén en inglés de docs/ (por ejemplo, docs/README.zh-CN.md)

4. Agrega una sección Languages al README.md principal:

   Traducciones: Las traducciones mantenidas por la comunidad están disponibles en la Wiki de GitHub. Para contribuir con una traducción o mejorar una existente, edita la Wiki directamente. Todas las lenguas son bienvenidas.

5. Crear una página Translations en el Wiki de GitHub con una tabla de los idiomas disponibles, su nivel de completitud y los colaboradores que los mantienen.

6. Opcionalmente: agrega una funcionalidad CLI zeroclaw docs --translate que use el proveedor de LLM configurado para traducir cualquier página de documentación bajo demanda, algo natural para un producto cuyo propósito completo es la asistencia con IA

4.4 El impacto de AGENTS.md

Elimina el requisito de seguimiento de i18n de docs-contract.md. Reemplázalo con: Las PRs de documentación se revisan únicamente en inglés. Las traducciones son mantenidas por la comunidad en la Wiki y no están sujetas a revisión de PR.

5. La división del repositorio y la wiki

5.1 La regla de decisión

Un documento reside en el repositorio si se volvería incorrecto cuando el código cambia. Reside en la Wiki si no.

Esta no es una regla difusa. Aplícala literalmente.

Un ADR registra por qué se tomó una decisión arquitectónica específica en un momento determinado. Si el código cambia, el ADR sigue describiendo con precisión lo que se decidió y cuándo. El código puede haber evolucionado alejándose de esa decisión, pero el registro sigue siendo preciso. → Repositorio.

Una guía de configuración inicial para configurar el canal de Telegram describe los pasos que un usuario realiza con la versión actual del software. Si el formato de configuración cambia, la guía queda obsoleta. → Esto parece que debería estar en el repositorio, pero no debería. Las guías de configuración inicial deberían actualizarse según su propio calendario, no estar acopladas a los commits del código. El modelo correcto es: la referencia de la API (que se corresponde directamente con los structs de configuración) vive en el repositorio, y la guía de configuración inicial que acompaña al usuario en el uso de esa API vive en la Wiki, actualizada por cualquiera cuando los pasos cambien.

5.2 La división en la práctica

Se mantiene en el repositorio (docs/book/src/):

Se traslada a la Wiki de GitHub (propuesto; aún no ejecutado):

Eliminado (eliminación de i18n):

5.3 La estructura del wiki

Home
│
├── Getting Started
│     ├── Installation
│     ├── Quick Start (TL;DR)
│     ├── Migrating from OpenClaw
│     └── Onboarding Walkthrough
│
├── Configuration
│     ├── Providers
│     ├── Channels
│     ├── Memory
│     ├── Security & Pairing
│     └── Tunnels
│
├── Channels
│     ├── Telegram
│     ├── Discord
│     ├── Slack
│     ├── WhatsApp
│     └── ... (one page per channel)
│
├── Operations
│     ├── Troubleshooting
│     ├── Deployment
│     ├── Network Setup
│     └── Performance Tuning
│
├── Hardware
│     ├── Getting Started with Peripherals
│     ├── ESP32 Setup
│     ├── STM32 Nucleo Setup
│     └── Arduino Setup
│
└── Community
      ├── FAQ
      ├── Translations
      └── How to Contribute

6. Estándares ADR

6.1 El formato

Todos los Architecture Decision Records usan el Nygard format, ampliado con frontmatter de YAML para que sea legible por máquinas. ADR-004 fue el modelo identificado por este RFC. Esta sección formaliza esa forma.

Cada ADR tiene tres secciones y cinco campos de frontmatter:

---
id: ADR-NNN
title: Oración imperativa corta que describe la decisión
date: YYYY-MM-DD
status: proposed | accepted | deprecated | superseded-by-ADR-NNN
relates-to:
  - ADR-XXX (opcional, lista de decisiones relacionadas)
  - crates/zeroclaw-api (opcional, rutas de código afectadas)
---

# ADR-NNN: Título

## Contexto

¿Cuál es la situación, restricción o problema que requirió una decisión?
¿Qué fuerzas estaban en juego? ¿Qué opciones se consideraron?

## Decisión

¿Qué se decidió? Exprésalo en voz activa.
"Vamos a..." en lugar de "Se decidió que..."

## Consecuencias

¿Cuáles son los resultados de esta decisión?
Enumera tanto las consecuencias positivas como las negativas: toda decisión tiene compensaciones.
Señala cualquier decisión o acción posterior que esto genere.

## Referencias

Enlaces a los archivos de código relevantes, problemas y recursos externos.

6.2 Reglas del ciclo de vida de ADR

• Los ADR son inmutables una vez aceptados. Si una decisión cambia, el ADR anterior se marca como superseded-by-ADR-NNN y se escribe un nuevo ADR que describe la nueva decisión y por qué sustituye a la anterior.
• Los ADR se numeran de forma secuencial y nunca se renumeran. Son aceptables los huecos en la secuencia (un ADR propuesto que fue rechazado puede ser retirado, dejando un hueco).
• Los ADRs viven en docs/book/src/architecture/decisions/. Se nombran ADR-NNN-short-slug.md.
• Los cambios arquitectónicos significativos requieren un ADR. “Significativo” significa: una decisión que sería sorprendente para un nuevo colaborador, una decisión que limita las opciones futuras o una decisión que implica un compromiso no evidente.

6.3 Conjunto Fundamental de ADR

Las siguientes decisiones fundacionales y objetivos de hoja de ruta cuentan con ADR duraderos. ADR-001 hasta ADR-005 son registros retroactivos de arquitectura que ya existe. ADR-006 y ADR-007 describen objetivos condicionados a la implementación de FND-001 y deben permanecer como propuestos hasta que se publiquen sus límites correspondientes.

Los ADRs retroactivos deben marcarse con una nota:

Este es un registro retrospectivo de una decisión tomada antes del proceso formal de ADR. La fecha refleja cuándo se tomó la decisión, no cuándo se escribió este registro.

Si se desconoce la fecha de la decisión original, usa la fecha en que se añadió el registro ADR y díselo en la nota. Si un ADR retroactivo ya está reemplazado por una decisión posterior, conserva el ADR histórico y escribe el ADR que lo reemplaza por separado.

6.4 Por qué esto es importante para el desarrollo asistido por IA

Cuando un asistente de codificación con IA lee un repositorio, ve el código tal como está en ese momento. No ve las opciones que fueron rechazadas, los compromisos que se evaluaron ni las razones por las que se eligió una estructura específica sobre otras alternativas. Sin ADRs, la IA propondrá cambios que violen restricciones arquitectónicas que no puede conocer. Con ADRs, el razonamiento es explícito y legible por máquina. El frontmatter hace que los ADRs sean consultables: una herramienta de IA puede encontrar todos los ADRs relacionados con zeroclaw-api y cargarlos como contexto antes de editar ese crate.

7. AGENTS.md como la capa de desarrollo de IA

7.1 El patrón

El archivo raíz AGENTS.md es el contrato compacto y siempre cargado del proyecto para el desarrollo asistido por IA. Contiene las políticas de seguridad, privacidad, autorización, contribución y validación a nivel de todo el proyecto. El mapa de arquitectura y contribución dirige las tareas no triviales a sus fuentes relevantes, mientras que las directrices del agente de programación conservan detalles opcionales como ejemplos, asignaciones de estabilidad actuales, descubrimiento de habilidades y documentos operativos protegidos. Este contrato por capas se mantiene específico y con criterio propio sin cargar todos los detalles en cada sesión.

A medida que el workspace se descompone en crates (según el RFC de arquitectura de microkernel), cada crate debe tener su propio AGENTS.md. Este es el mecanismo por el cual los límites arquitectónicos se vuelven aplicables en la capa de asistencia de IA, no solo en tiempo de compilación a través de las dependencias entre crates, sino en la capa de razonamiento antes de que se escriba cualquier código.

7.2 Qué contiene cada crate AGENTS.md

Mantenlos cortos. Un AGENTS.md que tenga más de 60 líneas no se leerá. Cada archivo responde a cinco preguntas:

# <crate-name>

## What this crate is
One or two sentences. What problem does this crate solve?

## What this crate is allowed to depend on
List the crates this crate may import. Be explicit.
If a dependency is not listed here, do not add it without an ADR.

## Extension points
Where can new implementations be added? What trait do they implement?
Link to the relevant traits.

## What does NOT belong here
Explicit anti-patterns. What would be a mistake to add to this crate?

## Related ADRs
- ADR-NNN: Short title

7.3 Ejemplos

Para crates/zeroclaw-api (una vez extraído):

# zeroclaw-api

## What this crate is
Trait definitions and shared data types for the ZeroClaw plugin and kernel
interfaces. This is the contract layer. Everything else depends on it.

## What this crate is allowed to depend on
- serde, serde_json (serialization)
- async-trait (async trait support)
- anyhow (error types)
- tokio (async runtime types, minimal)
Nothing else. No HTTP clients. No database drivers. No external services.

## Extension points
All traits in this crate are extension points:
- `Provider` (src/providers/traits.rs) — LLM provider implementations
- `Channel` (src/channels/traits.rs) — messaging platform integrations
- `Tool` (src/tools/traits.rs) — agent tool implementations
- `Memory` (src/memory/traits.rs) — persistence backends
- `Observer` (src/observability/traits.rs) — observability backends
- `RuntimeAdapter` (src/runtime/traits.rs) — execution environments
- `Peripheral` (src/peripherals/traits.rs) — hardware integrations

## What does NOT belong here
- Any concrete implementation of any trait
- Any dependency on a specific messaging platform, LLM provider, or database
- Any network I/O or filesystem access
- Any binary or executable target

## Related ADRs
- ADR-002: Trait-driven extensibility

Para crates/zeroclaw-kernel (una vez extraído):

# zeroclaw-kernel

## What this crate is
The orchestration engine. Runs the agent loop, manages the service registry,
exposes the local IPC API. The kernel knows nothing about specific channels,
providers, or tools — only their abstract interfaces.

## What this crate is allowed to depend on
- zeroclaw-api (traits only)
- zeroclaw-tool-call-parser (parsing, no agent state)
- Standard async/runtime crates (tokio, anyhow, tracing)
- Config and storage crates (toml, serde, rusqlite for core memory)
NOT: any specific channel, provider, or tool implementation crate.

## Extension points
- `Registry::register_channel()` — add a channel at startup
- `Registry::register_tool()` — add a tool at startup
- `Registry::set_provider()` — set the active provider at startup
Implementations are registered by the binary crate, not by the kernel.

## What does NOT belong here
- Any import of TelegramChannel, DiscordChannel, or any named channel
- Any import of AnthropicProvider, OpenAIProvider, or any named provider
- Any tool implementation beyond the 10-12 designated core tools
- The gateway HTTP server or any web serving code

## Related ADRs
- ADR-002: Trait-driven extensibility
- ADR-006: Optional channels migrate to runtime plugins
- ADR-007: Gateway extraction into a separate optional binary

7.4 La jerarquía de AGENTS.md

El AGENTS.md raíz establece la política compacta para todo el proyecto. El mapa de arquitectura y contribución dirige las tareas hacia fuentes mantenidas de arquitectura, fundamentos, pruebas, seguridad y mantenimiento. Las directrices para agentes de codificación proporcionan ejemplos detallados y registros para todo el proyecto que son útiles bajo demanda, pero no forman parte del arranque de carga inicial.

Los archivos AGENTS.md a nivel de crate acotan esa política para su ámbito específico. Cuando una herramienta de IA lee un archivo en crates/zeroclaw-api/, debe leer el contrato raíz, seguir el mapa de arquitectura para la tarea y leer crates/zeroclaw-api/AGENTS.md cuando esté presente. La política del crate es más específica y tiene prioridad dentro de su ámbito, pero no puede debilitar los requisitos de seguridad, privacidad o autorización de todo el proyecto.

8. La estructura de destino

Tras la migración a mdBook, la disposición de las fuentes de documentación adyacentes al código del repositorio es:

docs/book/src/
│
├── README.md                    ← mdBook introduction
├── SUMMARY.md                   ← Canonical mdBook TOC
│
├── architecture/
│   ├── overview.md              ← Current system landscape
│   ├── decisions/               ← ADRs (immutable once accepted)
│   │   ├── ADR-001-rust-first.md
│   │   ├── ADR-002-trait-driven-extensibility.md
│   │   ├── ADR-003-wasm-plugin-model.md
│   │   ├── ADR-004-tool-shared-state-ownership.md
│   │   ├── ADR-005-pluggable-memory-backends.md
│   │   ├── ADR-006-runtime-channel-plugins.md
│   │   ├── ADR-007-gateway-extraction.md
│   │   └── ADR-009-wit-wasmtime-plugin-execution.md
│   └── diagrams/
│       ├── component-map.md     ← Mermaid: crate topology
│       └── data-flow.md         ← Mermaid: message lifecycle
│
├── contributing/
│   ├── index.md
│   ├── architecture-map.md
│   ├── rfcs.md
│   ├── testing.md
│   └── pr-review-protocol.md
│
├── reference/
│   ├── index.md
│   ├── cli.md
│   ├── config.md
│   └── providers.md
│
├── security/
│   ├── overview.md
│   ├── model.md
│   ├── sandboxing.md
│   └── tool-receipts.md
│
├── hardware/
│   ├── index.md
│   ├── subsystem.md
│   ├── adding-boards-and-tools.md
│   └── hardware-peripherals-design.md
│
└── foundations/
    ├── fnd-001-intentional-architecture.md
    ├── fnd-002-documentation-standards.md
    ├── fnd-003-governance.md
    ├── fnd-004-engineering-infrastructure.md
    ├── fnd-005-contribution-culture.md
    └── fnd-006-zero-compromise-in-practice.md

Eliminado de la estructura actual:

docs/i18n/                       ← 169 files, 2.2 MB — removed entirely
docs/maintainers/                ← project snapshots and i18n coverage maps
                                   moved to Wiki (operational, not code-adjacent)
docs/setup-guides/               ← moved to Wiki
docs/ops/                        ← moved to Wiki
README.ar.md (and 30 others)     ← removed from repo root
docs/README.ar.md (and 30 others)← removed

El directorio raíz del repositorio queda limpio:

README.md
AGENTS.md
CHANGELOG.md
CLAUDE.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
SECURITY.md
LICENSE-APACHE
LICENSE-MIT
NOTICE
Cargo.toml
Cargo.lock
... (build and config files)

No hay variantes de idioma. No hay READMEs duplicados. Un único README en inglés que enlaza a la Wiki para las guías del usuario y al árbol docs/ para la referencia técnica.

9. El contrato de documentación de reemplazo

El archivo legado docs/contributing/docs-contract.md establecía un requisito de paridad de i18n y una estructura de directorios que esta RFC reemplaza. Se ha eliminado; esta sección es su sustitución.

El reemplazo regula tres cosas: la clasificación de artefactos, la separación entre repo y wiki, y la gobernanza de los ADR. No dice nada sobre i18n: la paridad de configuraciones regionales ahora se gestiona en la página Maintainers → Docs & Translations.

Documentación de reemplazo:

# Documentation Contract

## Document Classification

Every document in `docs/` belongs to one artifact family:

- **Considerations** — principles and standards that guide decisions
- **Landscapes** — descriptions of the current system state
- **Outlines** — proposals and roadmaps for future work
- **Designs** — ADRs, API specs, and detailed technical decisions
- **Standards** — specific rules for how we build and operate

If you cannot name the family before writing, do not write yet.

## The Repo / Wiki Rule

A document lives in the repository if it would become wrong when the
code changes. It lives on the Wiki if it would not.

Reference documentation (config reference, CLI reference) lives in the
repository because it maps directly to code structures.

User guides, setup instructions, and operational how-tos live on the Wiki
because they update on their own timeline.

## ADR Governance

See `docs/book/src/architecture/decisions/` for the ADR format and lifecycle rules.

Major architectural changes require an ADR before implementation begins,
not after.

## Language

All documents in this repository are written in English.
Community-maintained translations live on the GitHub Wiki.
Documentation PRs are reviewed in English only.

## Freshness

Documents should be updated in the same PR as the code change that makes
them stale. A PR that changes a configuration format must update the
config reference. A PR that adds a new command must update the CLI reference.

RFC issues and roadmap trackers are exempt - they describe intent and
may precede implementation by multiple releases.

10. Estándares que deberíamos adoptar

Estos estándares específicos de la documentación complementan los estándares más amplios propuestos en el RFC de arquitectura.

Marco de Diátaxis (Estructura de la Documentación)

Qué es: Diátaxis (https://diataxis.fr) es un framework sistemático para documentación técnica que divide el contenido en cuatro tipos: tutoriales, guías prácticas, referencia y explicación. Es el framework de documentación detrás de la documentación de Python, la documentación de Django y muchas otras. Es altamente compatible con el enfoque de EA Artifacts: responden a preguntas diferentes (Diátaxis: cómo estructurar el contenido de un documento; EA Artifacts: qué tipo de documento es este y dónde reside).

Cómo se aplica: La documentación dirigida al usuario en la Wiki debe seguir la estructura de Diátaxis. La documentación cercana al código en el repositorio sigue los Artefactos de EA. Los dos marcos operan a diferentes niveles y no entran en conflicto.

Frontmatter de Markdown para la legibilidad por máquina

Todos los documentos en docs/ deben incluir YAML frontmatter. Esto los hace consultables por herramientas de IA, verificaciones de CI y futuras herramientas:

---
tipo: adr | propuesta | referencia | contribución | seguridad | hardware
estado: borrador | propuesto | aceptado | obsoleto | reemplazado
última revisión: AAAA-MM-DD
relacionado-con:
  - ADR-NNN
  - crates/zeroclaw-api
---

Una verificación de CI debe comprobar que todos los documentos en docs/ tengan frontmatter válido. Esto evita que se escriban documentos sin declarar primero su tipo y estado, haciendo cumplir la disciplina de clasificación a nivel de las herramientas.

CommonMark + GitHub Flavored Markdown

Toda la documentación utiliza CommonMark (la especificación estandarizada de Markdown) con extensiones de GitHub Flavored Markdown (tablas, listas de tareas, bloques de código delimitados, diagramas de Mermaid). No se utilizan extensiones personalizadas, ni MDX, ni ReStructuredText. Se prefieren los diagramas de Mermaid sobre los archivos de imagen para los diagramas de arquitectura, ya que se versionan de manera limpia junto con el código.

Vale para la revisión de prosa

Qué es: Vale (https://vale.sh) es un linter de prosa: comprueba el estilo de escritura, la consistencia y la legibilidad mediante reglas configurables. Puede hacer cumplir cosas como: usar siempre “tú” en lugar de “el usuario”, evitar la voz pasiva en secciones imperativas, usar terminología consistente (“plugin” y no “extension” ni “module”).

Por qué es importante: La documentación actual es inconsistente en tono, terminología y estilo. Algunas páginas dicen “plugin”, otras “módulo” y otras “extensión”. Vale hace que estas reglas sean automáticas y las aplica durante la integración continua (CI), de la misma manera que Clippy aplica la calidad del código.

11. Hoja de ruta por fases

La migración de la documentación sigue el mismo patrón de la higuera estranguladora que la migración de la arquitectura: incremental, siempre en un estado funcional, sin reescrituras masivas.

Fase 1 · v0.7.0: “Limpiar la raíz”

Entregables:

• Elimina todos los archivos README.*.md de la raíz del repositorio (conserva solo README.md).
• Eliminar completamente docs/i18n/
• Eliminar todos los archivos de hub que no sean de inglés de docs/
• Agrega la sección Languages a README.md con el enlace a la Wiki
• Crea el Wiki de GitHub con la estructura base (Inicio + páginas de primer nivel, plantillas de contenido)
• Eliminar el requisito de paridad i18n de docs-contract.md
• Añade frontmatter YAML a todos los archivos existentes en docs/
• Crear docs/book/src/architecture/decisions/, agregar ADR-001 y ADR-002, restaurar ADR-003 y ADR-004, y añadir ADR-009 como registro de WIT/wasmtime que reemplaza a ADR-003

Métricas de éxito:

• La raíz del repositorio contiene exactamente un archivo README.
• docs/i18n/ no existe
• Todos los archivos de docs/ tienen un frontmatter YAML válido (verificado por CI).
• El Wiki de GitHub está activo y enlazado públicamente desde el README

Fase 2 · v0.7.0–v0.8.0: “Escribir los ADRs faltantes”

Entregables:

• Escribe ADR-005 como un registro retroactivo del contrato actual de almacenamiento en memoria

• No hay ninguna cadena de documentación técnica en inglés para traducir en tu mensaje.

  Por favor, proporciona la cadena de texto en inglés que deseas traducir al español y la traduciré siguiendo las reglas indicadas.

• Agrega una configuración de Vale (.vale.ini + reglas de estilo) y una verificación en CI

• Reemplaza docs-contract.md en su totalidad con la versión especificada en la Sección 9

• Migrar el contenido de docs/setup-guides/ al Wiki de GitHub

• Migrar el contenido de docs/ops/ al Wiki de GitHub

• Actualiza SUMMARY.md para reflejar la nueva estructura (contenido solo del repositorio)

• Escribir el AGENTS.md de nivel raíz para crates/zeroclaw-api (anticipándose a la extracción)

Métricas de éxito:

• Los ADR-001 a ADR-007 existen con el estado aceptado, propuesto o reemplazado, según corresponda
• ADR-009 registra la decisión de WIT/wasmtime que reemplaza a ADR-003
• La verificación de CI de Vale pasa en todos los documentos.
• La wiki tiene el contenido completo de todas las secciones migradas.
• No hay enlaces rotos en docs/

Fase 3 · v0.8.0–v0.9.0: “La capa de IA”

Entregables:

• Escribe AGENTS.md para cada nuevo crate a medida que el espacio de trabajo se descompone (según las fases del RFC de arquitectura).
• Escribe docs/book/src/architecture/diagrams/component-map.md (Mermaid, refleja la topología del crate de destino)
• Escribe docs/book/src/architecture/diagrams/data-flow.md (Mermaid, ciclo de vida del mensaje)
• Escribe la documentación del SDK del plugin en docs/book/src/developing/plugin-sdk.md
• Escribe la documentación de la interfaz WIT junto con los archivos wit/ (generados a partir de WIT + explicación escrita a mano)
• Actualiza la documentación de la especificación de OpenAPI a medida que la API de IPC del kernel se estabiliza

Métricas de éxito:

• Cada crate en el espacio de trabajo tiene un AGENTS.md
• Los diagramas de arquitectura son Mermaid (no se incluyen archivos de imagen binarios en docs/)
• La documentación del SDK del complemento es suficiente para que un colaborador externo escriba un complemento de herramienta funcional.

Fase 4 · v1.0.0: “La Plataforma Estable”

Entregables:

• Marca ADR-006 y ADR-007 como accepted una vez que se haya publicado el código correspondiente
• Versiona la documentación de la API de IPC del kernel en v1 con una garantía de estabilidad
• Escribir el documento de gobernanza de Plugin Registry (quién controla el registro, cómo se revisan los plugins y cómo se revocan los plugins comprometidos)
• Publicar el SDK del plugin como un sitio de documentación independiente (desde docs/book/src/developing/plugin-sdk.md)
• Establecer el rol de coordinador de traducción de la Wiki (un miembro de la comunidad que mantiene la página de traducciones y coordina a los traductores voluntarios)

Métricas de éxito:

• Todos los ADR fundamentales están aceptados
• El SDK del complemento está completo y se vincula externamente desde el README
• La wiki tiene traducciones mantenidas por la comunidad activas en al menos dos idiomas.
• La documentación CI (verificación de frontmatter + Vale) se ejecuta en cada PR.

Apéndice A: Glosario

ADR (Architecture Decision Record): Un registro inmutable de una decisión arquitectónica significativa: el contexto que la motivó, lo que se decidió y las consecuencias. Los ADR no cambian una vez aceptados; las decisiones reemplazadas se registran como nuevos ADR.

Diátaxis: Un marco sistemático para la estructura de documentación técnica que divide el contenido en tutoriales (aprendizaje), guías prácticas (orientadas a objetivos), referencia (información) y explicación (comprensión). Consulte https://diataxis.fr.

EA Artifacts on a Page: Un marco de clasificación para documentos de arquitectura empresarial desarrollado por Svyatoslav Kotusev. Clasifica los artefactos en cinco familias: Consideraciones (Considerations), Panoramas (Landscapes), Esquemas (Outlines), Diseños (Designs) y Estándares (Standards). Consulte https://eaonapage.com.

Frontmatter: Metadatos YAML al inicio de un archivo Markdown, delimitados por ---. Hace que los documentos sean legibles por máquinas y consultables por herramientas, verificaciones de CI y asistentes de IA.

Formato Nygard: El formato de ADR introducido por Michael Nygard: tres secciones (Contexto, Decisión, Consecuencias) que capturan el razonamiento esencial sin ceremonia innecesaria.

Patrón Strangler Fig: Una estrategia de migración en la que la nueva estructura se construye de forma incremental alrededor de la antigua, reemplazándola pieza por pieza en lugar de todo a la vez. El sistema permanece funcional durante toda la migración.

Vale: Un linter de prosa para documentación técnica. Aplica reglas de estilo, consistencia y legibilidad en tiempo de CI, de la misma manera que Clippy aplica la calidad del código Rust. Consulta https://vale.sh.

Apéndice B: Lecturas adicionales

• Marco de documentación Diátaxis: La referencia definitiva para estructurar documentación técnica por tipo.
• EA Artifacts on a Page (v2.2): El marco de clasificación utilizado en la Sección 3.
• “Docs for Developers”: Jared Bhatti et al.: Una guía práctica de documentación técnica escrita por ingenieros que han mantenido grandes sistemas de documentación.
• Documentación de Vale: Guía de configuración inicial y referencia de configuración para el linter de prosa propuesto en la Sección 10.
• Michael Nygard sobre ADRs: La publicación original que introdujo el formato ADR utilizado en la Sección 6.
• Documentación de GitHub Wikis: Referencia para configurar y administrar la GitHub Wiki propuesta en la Sección 5.

Esta propuesta se desarrolló a partir del análisis directo del sistema de documentación de ZeroClaw en la versión v0.6.8. Las métricas citadas (169 archivos i18n, 2,2 MB, 31 variantes de README en diferentes idiomas) se basan en mediciones directas. Las recomendaciones reflejan prácticas establecidas en documentación técnica para proyectos de infraestructura de código abierto, adaptadas a las restricciones y objetivos específicos de ZeroClaw.

Se aceptan comentarios, correcciones y contrapropuestas. Una buena documentación es un esfuerzo comunitario, y la mejor estructura es aquella que el equipo realmente mantendrá.