Escribir una página de contrato

Especificado. Describe la convención de dec-0124, que está propuesto. Hasta que se bloquee, las guardas que la imponen corren en modo informe y no bloquean CI. Esta página obliga a quien escribe documentación desde el primer día.

Por qué las páginas son un contratoCopiar enlace

La documentación de Styx no es un texto que se escribe al final: describe el sistema objetivo y obliga a que el código lo cumpla. Cada página declara a qué nodos, gates y decisiones está atada y en qué estado está. Un gate no puede pasar sin su documentación, y la referencia generada no puede desviarse del código.

El frontmatterCopiar enlace

Cada página lleva los campos de Fumadocs (title, description) más un tipo y un bloque contract:

---
title: Invitaciones
description: Invitar a alguien a tu servidor con un enlace o un código.
kind: guia # tutorial | guia | referencia | explicacion | producto | operacion | contribuir
contract:
  nodes: [track/identity] # al menos un nodo de styx.model.yml
  gates: ['track/identity:I3'] # opcional: nodo:item
  adrs: [dec-0118] # decisiones; una propuesta se cita igual
  status: especificado # especificado | implementado | verificado
  since: null # versión del tren en la que pasó a implementado
  audience: [usuario, operador] # usuario | operador | desarrollador | agente
  generated: null # o { source, generator, inputHash } en páginas generadas
---

Una página tiene un tipo. Si mezcla tutorial y referencia, se parte.

Los tres estadosCopiar enlace

La coherencia es en las dos direcciones: una página verificado con un item abierto es rojo, pero también lo es una página especificado cuando todos sus items ya pasaron. Que la documentación se quede atrás también falla. Una página no baja de estado sin que baje lo que cita.

Una página especificado sin decisión bloqueada detrás no se puede promover a implementado: las áreas de diseño abierto dicen «especificado — diseño pendiente de decisión» y enlazan su ticket.

Cómo no posponer la documentaciónCopiar enlace

1. Un nodo nuevo nace con su página. Un nodo en cola necesita al menos una página especificado en el mismo cambio.
2. Un item de gate no sale de abierto sin páginas que lo citen y estén en el estado que le corresponde. El manifiesto de evidencia gana un campo docs con esas páginas.
3. El verificador firma también la documentación: lee las páginas contra el camino de producción. Si la página promete algo que el código no hace, el item no pasa.
4. Los items que ya pasaron antes de adoptar la regla entran en un trinquete que sólo baja.

Qué no se escribe a manoCopiar enlace

• El estado de un gate. Se enlaza a la vista generada del roadmap, no se copia. La guarda de higiene falla si una página a mano copia el veredicto de un item o declara un contador de gates.
• La referencia: las rutas HTTP, el SDK, el bus, el CLI, la configuración y las páginas de roadmap y decisiones salen de sus fuentes (generadores). Lo que se escribe es el TSDoc, los comentarios /// y las descripciones de los contratos.
• Afirmaciones comparativas frente a otros servidores multimedia en producto/, sin una campaña de medición que las respalde (dec-0112).

Convenciones de FumadocsCopiar enlace

• El contenido está en apps/docs/content/docs/ y cada directorio tiene un meta.json con el título y el orden explícito de sus páginas. Las secciones de primer nivel van con separadores.
• El texto es MDX: en el cuerpo, {, }, < y > van entre comillas de código o escapados.
• Los enlaces entre páginas son relativos y sin extensión.
• El idioma canónico es el español.

Cada página debe poder leerse en GitHub y en el editor sin construir el sitio.