.

AI.md

@@ -79,8 +79,46 @@ const respostas = gerarRespostas((op) => {
 const r = respostas.erroInterno({ erro: new Error("boom"), local: "user.service" })
 ```
 
+## Validação com Zod (`zRespostas`)
+
+Para validar payloads de resposta recebidos de APIs ou serviços com [Zod](https://zod.dev):
+
+```ts
+import z from "zod"
+import { zRespostas, type tipoZResposta } from "p-respostas"
+
+// 1. Validando payload com tipo específico de sucesso
+const schemaUsuario = zRespostas(
+  z.object({
+    id: z.string(),
+    nome: z.string(),
+  })
+)
+
+const resposta = schemaUsuario.parse(jsonRecebidoDaApi)
+
+if (resposta.eCerto) {
+  // TypeScript sabe que resposta.valor tem { id: string; nome: string }
+  console.log("Dados do usuário:", resposta.valor.nome)
+} else {
+  // TypeScript sabe que resposta.mensagem é string e cod é um dos códigos de erro
+  console.error("Falha:", resposta.mensagem, "Código:", resposta.cod)
+}
+
+// 2. Aceitando qualquer valor no sucesso (default z.any())
+const schemaGenerico = zRespostas()
+
+// 3. Schemas e tipos auxiliares exportados:
+// - zResposta (alias idêntico a zRespostas)
+// - zRespostaSucesso(zValor?)
+// - zRespostaErro
+// - zCodigosRespostaErro
+// - tipoZResposta<T>
+```
+
 ## Garantias / restrições
 
 - Este pacote é amplamente importado por outros projetos.
 - Os arquivos em `dist-*` são gerados automaticamente.
 - Mudanças aqui devem focar em **melhorar o consumo (exports/tipos/docs)** sem alterar comportamento.
+