# Guia de estilo editorial

Este guia padroniza a escrita, a formatação e as convenções do Manual de
Pecuária. Todos os agentes e colaboradores devem segui-lo. Ele complementa as
instruções específicas em `agents/`.

## Autoria e cabeçalho de capítulo

- **Autor do manual:** Maurício Bomfim Cruz Vieira. A autoria é registrada uma
  vez no `book/README.md` e, quando o Prefácio for redigido, também na abertura
  dele; não se repete a assinatura em cada capítulo.
- **Cabeçalho de capítulo.** Esta é a convenção **daqui para frente**: à medida
  que cada capítulo é escrito ou atualizado, o arquivo em `book/` deve começar
  com o título em H1 e, logo abaixo, um comentário HTML de metadados (invisível
  na leitura) que liga o capítulo à sua especificação e registra o status.
  Capítulos ainda em *stub* podem não seguir o cabeçalho até serem redigidos.
  Exemplo:

  ```markdown
  # Título do capítulo

  <!--
  autor: Maurício Bomfim Cruz Vieira
  spec: docs/specs/NN-tema.md
  status: em redação        # rascunho | em redação | em revisão | pronto
  atualizado_em: AAAA-MM-DD
  -->
  ```

  O metadado fica em comentário para não poluir o texto final que o leitor lê.
  Contribuidores adicionais, quando houver, são creditados no `book/README.md`.

## Público-alvo e tom

- O leitor principal é **leigo ou produtor iniciante**.
- Escreva em **português brasileiro**.
- Use linguagem **direta, simples e prática**. Frases curtas. Parágrafos
  curtos.
- Técnico, mas acessível. Explique sem infantilizar.
- Evite tom acadêmico excessivo e evite tom de propaganda.

## Honestidade técnica

- **Nunca invente dados.** Todo número tem fonte ou premissa explícita.
- Separe com clareza: **fato**, **recomendação**, **estimativa** e **opinião**.
- Separe **prática recomendada**, **alternativa aceitável** e **prática
  arriscada**.
- Nunca prometa lucro, produtividade ou retorno garantidos.
- Quando o tema exigir, diga explicitamente que é preciso consultar
  veterinário, zootecnista, agrônomo, contador ou órgão público.
- Quando houver variação regional, deixe isso claro (com atenção especial à
  Bahia e ao Sudoeste baiano).

## Formatação Markdown

- Um `#` (H1) por arquivo, no título do capítulo ou documento.
- Hierarquia de seções com `##`, `###` — sem pular níveis.
- Listas com `-`. Listas de tarefas com `- [ ]`.
- Boxes de atenção com blockquote e um prefixo padronizado:
  - `> **Atenção:** ...` — risco ou cuidado importante.
  - `> **Dica:** ...` — boa prática opcional.
  - `> **Consulte um profissional:** ...` — exige apoio técnico/legal.
- Código, comandos e nomes de arquivo em `monoespaçado`.
- Marque pendências como `TODO:` no texto.

## Números, unidades e datas

- Use o Sistema Internacional e unidades usuais do setor (L, kg, ha, UA,
  L/vaca/dia, R$/L).
- Sempre indique a unidade.
- Use vírgula como separador decimal (padrão pt-BR): `12,5 L`.
- Evite precisão falsa: poucos decimais quando os dados são estimativas.
- Dados dependentes de preço atual são marcados como **atualizáveis**, com a
  data de referência.

## Siglas e termos técnicos

- Explique a sigla na **primeira ocorrência**: "unidade animal (UA)".
- Termos técnicos recorrentes vão para o glossário global (`docs/glossary.md`).
- Não redefina no capítulo um termo já no glossário; referencie-o.

## Tabelas, diagramas e figuras

- Toda tabela e todo diagrama têm **título** e, quando usam dados, **fonte**.
- Diagramas ficam em `diagrams/` e são referenciados no capítulo.
- Toda figura/diagrama tem **texto alternativo** (acessibilidade).
- Cálculos ficam em `calculations/` e o capítulo referencia o modelo em vez de
  repetir a conta.

## Referências

- Referências reutilizáveis ficam em `references/`. Evite duplicar metadados
  bibliográficos dentro do capítulo.
- Priorize fontes oficiais e acadêmicas: Embrapa, MAPA, universidades
  brasileiras, associações de raça, artigos revisados por pares. FAO quando
  útil.
- Fonte comercial não é evidência técnica principal (aceitável para preços,
  equipamentos e disponibilidade de mercado).
- Legislação: sempre indicar que deve ser conferida na versão vigente.

## Estrutura padrão de capítulo

Ver `templates/capitulo.md`. Em resumo:

1. Título
2. Resumo
3. Objetivos de aprendizagem
4. Por que este tema importa
5. Conceitos fundamentais
6. Como aplicar na prática
7. Erros comuns
8. Exemplo prático
9. Checklist
10. Perguntas frequentes
11. Referências

## Nomes de arquivo

- Minúsculas, sem acento, com hífen: `custo-por-litro.md`.
- Capítulos e specs prefixados por número: `02-economia-do-leite.md`.