diff --git a/AI.md b/AI.md
new file mode 100644
index 0000000..ec46bb5
--- /dev/null
+++ b/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.
+
diff --git a/README.md b/README.md
index 6896378..2120d75 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,74 @@
-# drivers
+# p-respostas
+
+Contrato simples e tipado de respostas para APIs e serviços (sucesso/erro), com suporte a:
+
+- **ESM** (`import`) via `dist-front/index.mjs`
+- **CommonJS** (`require`) via `dist-back/index.js`
+- **TypeScript** com tipos publicados em `dist-front/index.d.mts`
+
+> Importante: os diretórios `dist-*` são gerados automaticamente no build. Este repositório deve manter **compatibilidade** e **não alterar funcionalidades**.
+
+## Instalação
+
+```bash
+pnpm add p-respostas
+# ou
+npm i p-respostas
+```
+
+## Uso rápido
+
+```ts
+import { respostaComuns, gerarRespostas, codigosResposta, type tipoResposta } from "p-respostas"
+
+const r1 = respostaComuns.valor({ ok: true })
+// r1.cod === 200
+
+const r2 = respostaComuns.erro("Falha ao processar")
+// r2.eErro === true
+
+// Exemplo com logger/observabilidade
+const respostas = gerarRespostas(({ erro, mensagem, local }) => {
+  console.error("erroInterno:", { erro, mensagem, local })
+  // pode sobrescrever parcialmente a resposta final
+  return { detalhes: ["contate o suporte" as const] }
+})
+
+const r3: tipoResposta<string> = respostas.valor("ok")
+const r4: tipoResposta<string> = respostas.erroInterno({ erro: new Error("boom"), local: "serviceX" })
+```
+
+## API
+
+### `codigosResposta`
+
+Enum com os códigos HTTP usados pelo contrato:
+
+- `sucesso = 200`
+- `erroConhecido = 400`
+- `erroPermissao = 401`
+- `erroNaoEncontrado = 404`
+- `erroDesconhecido = 500`
+- `tempoEsgotado = 504`
+
+### Tipos
+
+- `tipoRespostaSucesso<T>`
+- `tipoRespostaErro`
+- `tipoResposta<T> = tipoRespostaSucesso<T> | tipoRespostaErro`
+- `tipoPrErroInterno`
+
+### `gerarRespostas(registrarErroInterno)`
+
+Cria um conjunto de funções padronizadas para gerar respostas.
+
+`registrarErroInterno(op)` recebe `{ erro, mensagem?, local, __filename? }` e pode retornar um `Partial<tipoRespostaErro>` para complementar a resposta final.
+
+### `respostaComuns`
+
+Instância default de `gerarRespostas(() => ({}))`.
+
+## Compatibilidade
+
+- Node: `>=20`
+- Exporta ESM e CJS via `package.json#exports`
diff --git a/dist-front/index.d.mts b/dist-front/index.d.mts
index 6251cb1..8f6d345 100644
--- a/dist-front/index.d.mts
+++ b/dist-front/index.d.mts
@@ -1,3 +1,8 @@
+/**
+ * Códigos padrão usados pelo contrato de respostas.
+ *
+ * Observação: este enum é parte da API pública do pacote.
+ */
 declare enum codigosResposta {
     sucesso = 200,
     erroConhecido = 400,
@@ -29,6 +34,11 @@ type tipoPrErroInterno = {
     local: string;
     __filename?: string;
 };
+/**
+ * Cria um conjunto de geradores de respostas.
+ *
+ * @param registrarErroInterno callback para registrar/normalizar erros internos.
+ */
 declare const gerarRespostas: (
 /** Faz um processamento quando erro interno
  * Recebe o erro gerado, mensagem personalizada e detalhes
@@ -68,7 +78,7 @@ registrarErroInterno: (op: tipoPrErroInterno) => Partial<tipoRespostaErro>) => {
     erroEspera: (mensagem?: string | undefined | null, detalhes?: string[]) => tipoRespostaErro;
 };
 /**
- * Uso de respostas em comuns
+ * Instância default (sem handler de erro interno).
  */
 declare const respostaComuns: {
     /**
diff --git a/package.json b/package.json
index 4a6b6ef..ec14b39 100644
--- a/package.json
+++ b/package.json
@@ -1,16 +1,21 @@
 {
   "name": "p-respostas",
-  "version": "0.54.0",
-  "description": "",
-  "main": "./src/index.ts",
+  "version": "0.56.0",
+  "description": "Contrato simples de respostas (sucesso/erro) para APIs e serviços.",
+  "main": "./dist-back/index.js",
+  "module": "./dist-front/index.mjs",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
+      "types": "./dist-front/index.d.mts",
       "import": "./dist-front/index.mjs",
       "require": "./dist-back/index.js"
     }
   },
-  "types": "./src/index.ts",
+  "types": "./dist-front/index.d.mts",
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
   "scripts": {
     "biome": "npx @biomejs/biome check --write ./src",
     "build": "npm --no-git-tag-version version minor && pnpm run biome && tsup --config ./node_modules/p-comuns/tsup/tsup.config.ts && pnpm run pacote",
diff --git a/pacote.tgz b/pacote.tgz
index a108c65..8381adf 100644
Binary files a/pacote.tgz and b/pacote.tgz differ
diff --git a/src/index.ts b/src/index.ts
index 565aacc..9f14c03 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1 +1,2 @@
+// Re-export da API pública do pacote.
 export * from "./respostas"
diff --git a/src/respostas.ts b/src/respostas.ts
index 0f37f3c..245b910 100644
--- a/src/respostas.ts
+++ b/src/respostas.ts
@@ -1,3 +1,8 @@
+/**
+ * Códigos padrão usados pelo contrato de respostas.
+ *
+ * Observação: este enum é parte da API pública do pacote.
+ */
 export enum codigosResposta {
   sucesso = 200,
   erroConhecido = 400,
@@ -39,6 +44,11 @@ export type tipoPrErroInterno = {
   __filename?: string
 }
 
+/**
+ * Cria um conjunto de geradores de respostas.
+ *
+ * @param registrarErroInterno callback para registrar/normalizar erros internos.
+ */
 export const gerarRespostas = (
   /** Faz um processamento quando erro interno
    * Recebe o erro gerado, mensagem personalizada e detalhes
@@ -178,6 +188,6 @@ export const gerarRespostas = (
 }
 
 /**
- * Uso de respostas em comuns
+ * Instância default (sem handler de erro interno).
  */
 export const respostaComuns = gerarRespostas(() => ({}))