Como contribuir

Esta documentação é construída a partir de definições fornecidas pelos engenheiros e arquitetos responsáveis pelo NEAD Hub. Contribuições devem preservar a origem das decisões e deixar visível o que ainda precisa de resposta.

Antes de editar

1. Identifique o domínio, a camada e o responsável pela definição.
2. Reúna o material fornecido ou indicado expressamente pelo responsável e registre uma referência localizável.
3. Verifique a página existente e anote as dúvidas que o material não resolve.
4. Leia AGENTS.md e a skill nead-domain-docs no repositório. Para contratos de API, aplique também nead-api-contracts; para regras de negócio, nead-business-rules.

Consulte a estrutura da documentação para decidir onde cada definição pertence. Uma consulta ao código pode apoiar uma verificação solicitada, mas não substitui a decisão de quem responde pelo domínio.

Escreva na camada correspondente

Preencha somente os campos cobertos pelo material recebido. Use termos consistentes com o Overview e registre referências entre histórias, páginas, operações e regras quando essas relações forem informadas. Registre um fluxo crítico na própria página de Histórias do usuário somente quando o material trouxer contexto complementar, como vários atores, estados, transação, compensação, integração ou alternativas relevantes. Mantenha perguntas e pendências explícitas para os pontos sem definição.

Para novos domínios, o comando abaixo cria as seis páginas iniciais em estado empty, fora da navegação pública:

npm run docs:new -- meu-dominio "Meu domínio"

Quando o refinamento de um domínio começar, npm run docs:visibility -- <slug> show o inclui no site. hide o retira da navegação, da busca e das rotas publicadas sem apagar seus arquivos. A visibilidade não representa aprovação editorial.

Registre a origem e o estado

Cada página de domínio exporta um registro documentation e exibe seu estado ao leitor.

Aguardando definição (empty): mantenha o roteiro intacto e os campos de autoria e aprovação como null.

Rascunho (draft): registre owner e source, preencha o que foi definido e mantenha approvedBy e approvedAt como null.

Aprovado (approved): use somente depois de uma aprovação humana expressa. Registre aprovador, data e referência da decisão. Uma mudança de significado devolve a página a draft até nova revisão.

Use US-DOMINIO-NNN e RN-DOMINIO-NNN para histórias e regras efetivamente definidas. Fluxos críticos não recebem identificador próprio: devem explicitar as histórias que complementam. Diagramas ER em Mermaid podem ser apresentados com ERDiagram quando o modelo for fornecido ou aprovado.

Revise e valide

npm run check
npm run build

Revise o significado com o responsável, confira autoria e fonte, links entre camadas, navegação e apresentação das páginas afetadas. O validador confere a estrutura e os registros editoriais; a aprovação do conteúdo exige uma decisão humana registrada. Ao enviar a contribuição, descreva o material recebido, o que mudou e as pendências abertas.