---
name: paebiru-docs
description: >
  Use ao criar ou revisar documentação Markdown no projeto PAEBIRU — especialmente
  arquivos em docs/src/ e READMEs de crates. Garante frontmatter YAML correto,
  kebab-case em nomes de arquivo, links relativos, organização por trilha de público
  e conformidade com o glossário canônico. Ative também ao criar runbooks,
  bounded context docs, ou guias de contribuição.
---

# paebiru-docs

Skill para produção de documentação no ecossistema PAEBIRU. Baseada em
`docs/src/contributors/writing-docs.md` e nas regras canônicas de `AGENTS.md` §9.

## 1. Metadados Documentários

O mdBook **não processa YAML frontmatter** — blocos `---` no topo do arquivo são
renderizados como texto visível. Por isso, **nunca use frontmatter YAML** em
arquivos `.md` de `docs/src/`.

### Alternativas para metadados:

1. **Comentários HTML** (não aparecem no output):
   ```html
   <!--
   title: Título Descritivo da Página
   audience: contribuindo
   status: revisado
   rfc-refs: [042, 050]
   -->
   ```

2. **`SUMMARY.md`** do mdBook (estrutura e títulos de navegação):
   ```markdown
   - [Título Descritivo](./caminho/arquivo.md)
   ```

3. **Primeiro heading H1** como título canônico da página:
   ```markdown
   # Título Descritivo da Página
   ```

## 2. Nomenclatura de Arquivos

- **kebab-case** em 100% dos arquivos `.md`. Ex: `mesh-topology.md`, `getting-started.md`
- **Exceção única**: RFCs usam `rfcNNN_nome-curto.md` (numeração imutável)
- Proibido: `GuiaRapido.md`, `getting_started.md`, `TEMP-DOC.md`, `fix_final.md`

## 3. Links — Caminhos Relativos Obrigatórios

**Proibido** caminhos absolutos ou URLs absolutas para conteúdo interno.

| Proibido | Correto |
|----------|---------|
| `/docs/src/architecture/kernel.md` | `./architecture/bounded-contexts/kernel.md` |
| `https://github.com/silvanoneto/paebiru/blob/main/docs/src/...` | `./architecture/bounded-contexts/kernel.md` |
| `C:\Users\...\paebiru\docs\...` | `./operators/runbooks/flash-stm32.md` |

Dica: links para RFCs sempre apontem para o arquivo, não para o README:
```markdown
Veja [RFC 050](./rfc050_four_dogmas.md) para os dogmas arquiteturais.
```

## 4. Organização por Trilha

Escolha o diretório correto baseado no público-alvo:

| Trilha | Diretório | Conteúdo Típico |
|--------|-----------|-----------------|
| Estou chegando | `docs/src/getting-started/` | Instalação, primeiro plasmídeo, CLI básica |
| Vou operar | `docs/src/operators/` | Runbooks, troubleshooting, flashing, observabilidade |
| Vou contribuir | `docs/src/contributors/` | Processo, qualidade, RFCs, verificação formal |
| Referência | `docs/src/reference/` | Dicionário, matemática, padrões, SDK |
| Arquitetura | `docs/src/architecture/` | Bounded contexts, visões prospectivas |
| Teoria | `docs/src/theory/` | Fundamentos cognitivos, termodinâmicos |
| RFCs | `docs/src/rfc/` | Especificações normativas |

## 5. Glossário Canônico

O [`docs/src/reference/dictionary.md`](../../docs/src/reference/dictionary.md) é a fonte de verdade para termos.

**Regra de ouro**: em caso de divergência entre `AGENTS.md`, comentários de código e `dictionary.md`, **o DICTIONARY vence**.

Termos que devem ser usados consistentemente:
- `Algedonic` (não "algedônico" em inglês; em pt-BR mantemos o termo técnico)
- `Maturidade Causal` (não "maturidade causal" minúsculo em títulos)
- `Langevin Ticks` (não "ticks de Langevin")
- `Bounded Context` (capitalizado quando se refere ao padrão DDD)
- `Plasmídeo` (não "plasmid", exceto em contexto biológico real)

## 6. Diagramas

- Use **Mermaid.js** para todos os diagramas.
- Mantenha diagramas code-first (não exporte imagens).
- Tipos preferidos: `graph TD` (fluxo), `sequenceDiagram` (interação), `classDiagram` (modelo).

Exemplo:
```markdown
```mermaid
graph TD
    A[Usuário] -->|paebiru-cli| B[Node]
    B -->|gossipsub| C[Malha P2P]
    C -->|DVV sync| D[C.A.P.I.B.A.]
```
```

## 7. Código em Documentação

- Blocos de código devem indicar linguagem: ````rust`, ````toml`, ````bash`, ````mermaid`
- Código Rust em docs deve compilar (use `mdbook test` quando possível).
- Comandos de shell devem ser copiáveis e funcionais no ambiente do projeto.

## 8. Trilhas de Público — Tom e Profundidade

| Trilha | Tom | Profundidade | Exemplo de frase |
|--------|-----|--------------|------------------|
| Chegando | Acolhedor, instrutivo | Conceitual, passo a passo | "Primeiro, instale o Rust com rustup..." |
| Operando | Direto, pragmático | Procedural, comandos exatos | "Execute `probe-rs run --chip STM32F407VG`..." |
| Contribuindo | Preciso, normativo | Técnica, referências a RFCs | "Conforme RFC 050 §2, todo crate deve..." |
| Referência | Conciso, canônico | Definições, matemática, tabelas | "Algedonia: capacidade de sentir dor..." |

## 9. Checklist de Documentação

- [ ] **Sem frontmatter YAML** no topo do arquivo (mdBook não processa)
- [ ] Nome do arquivo em kebab-case (exceto RFCs)
- [ ] Todos os links são relativos e funcionam
- [ ] Termos técnicos seguem `dictionary.md`
- [ ] Diagramas usam Mermaid (não imagens)
- [ ] Blocos de código têm linguagem explicitada
- [ ] Tom adequado à trilha de público
- [ ] Não há informação duplicada com outro arquivo (prefira link)

Para orientações sobre estrutura de documentos por tipo, veja:
[references/FRONTMATTER.md](references/FRONTMATTER.md)