refatoração para ia

AI.md

@@ -0,0 +1,80 @@
+# AI / LLM usage notes (p-respostas)
+
+Este pacote fornece um **contrato estável** de respostas para operações (principalmente APIs), representando:
+
+- sucesso (`cod: 200`, `eCerto: true`, `eErro: false`, `mensagem: undefined`, `valor: T`)
+- erro conhecido/permissão/não encontrado/timeout/erro interno (`cod` diferente de 200, `eErro: true`, `eCerto: false`, `valor: undefined`, `mensagem: string`)
+
+## Imports
+
+### TypeScript / ESM
+
+```ts
+import {
+  codigosResposta,
+  gerarRespostas,
+  respostaComuns,
+  type tipoResposta,
+  type tipoRespostaErro,
+  type tipoRespostaSucesso,
+  type tipoPrErroInterno,
+} from "p-respostas"
+```
+
+### CommonJS
+
+```js
+const { respostaComuns, gerarRespostas, codigosResposta } = require("p-respostas")
+```
+
+## Como interpretar uma `tipoResposta<T>`
+
+Regras úteis para checagem:
+
+- Se `res.eCerto === true` então:
+  - `res.cod === codigosResposta.sucesso`
+  - `res.valor` existe (tipo `T`)
+  - `res.mensagem` é `undefined`
+
+- Se `res.eErro === true` então:
+  - `res.valor` é sempre `undefined`
+  - `res.mensagem` é sempre `string`
+  - `res.cod` é um dos códigos de erro
+
+Exemplo:
+
+```ts
+function handle<T>(res: tipoResposta<T>) {
+  if (res.eErro) {
+    // aqui o TS entende tipoRespostaErro
+    return { ok: false as const, status: res.cod, message: res.mensagem }
+  }
+
+  // aqui o TS entende tipoRespostaSucesso<T>
+  return { ok: true as const, value: res.valor }
+}
+```
+
+## Como gerar respostas com log de erro interno
+
+```ts
+const respostas = gerarRespostas((op) => {
+  // op.erro: qualquer coisa lançada
+  // op.local: string (obrigatória)
+  // op.mensagem: string opcional
+  // op.__filename: opcional
+  console.error("Erro interno", op)
+
+  // Pode retornar complementos não-destrutivos
+  return { detalhes: ["id de rastreio: ..."] }
+})
+
+const r = respostas.erroInterno({ erro: new Error("boom"), local: "user.service" })
+```
+
+## 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.
+