diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c22cd86..0f09963 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -20,12 +20,12 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 2
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: ${{ matrix.node-version }}
           cache: npm
@@ -49,10 +49,10 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: 22.x
           cache: npm
diff --git a/README.md b/README.md
index 9ccbbae..76b9c13 100644
--- a/README.md
+++ b/README.md
@@ -1,160 +1,341 @@
-# Adao
+# Adão
 
 [![CI status](https://github.com/Laurowd/Adao/actions/workflows/ci.yml/badge.svg)](https://github.com/Laurowd/Adao/actions/workflows/ci.yml)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Adao is a local CLI productivity tool for projects that use code agents. It scans a project, checks whether `AGENTS.md` still matches the codebase, and can generate a short suggested replacement.
+English | [Português](README.pt-BR.md)
 
-The MVP does not use an external API, LLM, database, authentication, Tauri, or a graphical UI. It is focused on a small, testable core that a future UI can reuse.
+Adão is a local-first CLI for projects that use `AGENTS.md`. It scans a
+project, audits whether its instructions still match local evidence, generates
+deterministic context, prepares a structured prompt for a separate AI review,
+and safely applies managed updates.
 
-## Why it exists
+## Why Adão exists
 
-AI coding agents depend on reliable project context. A stale, vague, or oversized `AGENTS.md` can make the agent follow the wrong commands or waste context window budget. Adao acts as a local "Context Doctor" for that file.
+Coding agents rely on accurate project instructions. An outdated, vague, or
+oversized `AGENTS.md` can point to missing commands, describe the wrong stack,
+or consume context without helping.
 
-## Install
+Adão turns evidence already present in a repository into a repeatable workflow:
+inspect the project, diagnose suspicious instructions, generate a conservative
+baseline, optionally prepare that evidence for external AI review, and update
+only the content Adão manages when markers are present.
 
-The `0.1.0` package is prepared for npm but has not been published yet. After
-publication, it can be installed or executed with:
+## Quick start
+
+Adão requires Node.js 18 or later. The package is prepared as
+`@laurowd/adao`, but it has **not been published to npm yet**. To use the
+current version from a checkout:
 
 ```bash
-npm install -g @laurowd/adao
-npx @laurowd/adao --help
+git clone https://github.com/Laurowd/Adao.git
+cd Adao
+npm ci
+npm run build
+node dist/cli.js --help
 ```
 
-For local development from a checkout:
+The planned commands below apply only **after the package is published**:
 
 ```bash
-npm install
-npm run build
-node dist/cli.js --help
+npm install -g @laurowd/adao
+npx @laurowd/adao --help
 ```
 
-## Develop
+The five project commands cover distinct parts of the workflow:
+
+| Command | Purpose |
+| --- | --- |
+| `scan` | Inventory project evidence such as languages, scripts, tools, and structure. |
+| `doctor` | Check whether the current `AGENTS.md` is still consistent with detected evidence. |
+| `generate` | Print a deterministic `AGENTS.md` baseline derived from local evidence. |
+| `suggest` | Build a structured prompt for a separate review by Codex, ChatGPT, or another AI. |
+| `apply` | Preview and safely write the generated managed content. |
+
+From a development checkout:
 
 ```bash
 npm run dev -- scan .
 npm run dev -- doctor .
 npm run dev -- generate .
 npm run dev -- suggest .
+npm run dev -- apply .
 ```
 
-Build and test:
+## Commands
 
-```bash
-npm run build
-npm test
-npm run test:package
+The current CLI contract is:
+
+```text
+adao scan <projectPath> [--json]
+adao doctor <projectPath> [--json]
+adao generate <projectPath>
+adao suggest <projectPath> [--json]
+adao apply <projectPath> [--yes]
+
+adao --help
+adao --version
 ```
 
-After building, the CLI entry is available at `dist/cli.js`. The package also exposes the `adao` binary when installed as a package.
+`scan`, `doctor`, and `suggest` support optional JSON output. `apply` asks for
+confirmation unless `--yes` is supplied. Invalid usage exits with code `2`;
+operational failures and a `doctor` result containing errors exit with code `1`.
+Usage and operational errors are concise and do not print stack traces.
 
-## Commands
+Each command also supports command-specific help, for example
+`adao apply --help`.
+
+### `scan`
 
-### scan
+`scan` reads the project tree and collects evidence including:
 
-Analyze a project directory.
+- project name, package description, and a locally derived overview;
+- languages detected from file extensions;
+- a conservative set of frameworks and tools detected from package metadata;
+- package scripts and package manager evidence;
+- important files and relevant project directories;
+- the presence of `README.md`, Git metadata, and `AGENTS.md`.
+
+The default text output summarizes the scan; `--json` exposes the complete
+structured result, including package description and derived overview fields.
 
 ```bash
-npm run dev -- scan .
-npm run dev -- scan . --json
+adao scan .
+adao scan . --json
 ```
 
-Example output:
+The scanner examines up to 5,000 filesystem entries by default and reports how
+many entries it inspected, whether the limit was reached, and any unreadable
+paths. Its text and JSON output expose whether the result is complete. A
+truncated scan or a blocking filesystem error makes the evidence incomplete;
+`doctor` reports that condition as an error, while `generate`, `suggest`, and
+`apply` refuse to continue from partial evidence.
 
-```text
-Project: adao
-Path: /path/to/adao
-Git repository: no
-AGENTS.md: no
-README.md: yes
-Package manager: npm
-Languages: TypeScript
-Frameworks/tools: Vitest
-Project structure: src/, tests/
-Scripts:
-  dev: node --import tsx src/cli.ts
-  build: tsc -p tsconfig.json
-  test: vitest run
-Important files: package.json, tsconfig.json
-```
+Detection is deliberately finite rather than universal. Language detection is
+extension-based, and framework/tool detection recognizes a defined set of
+package dependencies.
 
-### doctor
+### `doctor`
 
-Validate `AGENTS.md` and report `error`, `warning`, and `info` issues.
+`doctor` validates the current `AGENTS.md` against detected project evidence
+and reports `error`, `warning`, and `info` issues, followed by a `healthy`,
+`needs attention`, or `broken` status.
 
 ```bash
-npm run dev -- doctor .
+adao doctor .
+adao doctor . --json
 ```
 
-Checks include:
+Checks currently cover cases such as:
+
+- a missing `AGENTS.md`;
+- package commands that do not match available `package.json` scripts;
+- commands that use a package manager inconsistent with detected evidence;
+- stack declarations that appear inconsistent with the detected project;
+- vague guidance and excessive file size;
+- possible staleness when `README.md` or `package.json` is newer;
+- a simple package-manager conflict with global `~/.codex/AGENTS.md` guidance;
+- an incomplete project scan.
 
-- missing `AGENTS.md`
-- commands in `AGENTS.md` that do not exist in `package.json`
-- mentioned stack that was not detected in the project
-- files over 4000 or 8000 characters
-- vague phrases such as "write clean code"
-- `AGENTS.md` older than `package.json`, lockfiles, or `README.md`
-- simple conflict with `~/.codex/AGENTS.md` package manager guidance
+Stack validation is heuristic and conservative. It looks for assertive stack
+declarations and avoids treating negative guidance or clearly hypothetical
+examples as project facts. A lockfile becoming newer does not, by itself, make
+`AGENTS.md` stale.
 
-### generate
+### `generate`
 
-Print a suggested `AGENTS.md` without writing to disk.
+`generate` prints an `AGENTS.md` draft without writing files or calling an
+external service.
 
 ```bash
-npm run dev -- generate .
+adao generate .
 ```
 
-The generated overview only uses reliable local sources:
+Generation is deterministic and uses only local evidence such as validated
+`package.json` metadata, `README.md`, package scripts, detected stack, package
+manager evidence, and project structure. A package description takes priority
+for the project overview; otherwise Adão uses useful README content. When the
+available evidence is not sufficient, it writes an explicit `TODO` instead of
+inventing a goal, command, stack, or architecture.
+
+Generated content is wrapped in a managed region:
+
+```markdown
+<!-- adao:start -->
 
-1. `package.json.description`
-2. the first heading or useful paragraph from `README.md`
-3. `TODO: describe the project goal.`
+<!-- generated content -->
 
-When no commands or structure can be detected, Adao writes explicit TODOs instead of inventing context. If scripts such as `test`, `build`, `lint`, or `typecheck` exist, `generate` also adds a `Validation` section with the relevant commands.
+<!-- adao:end -->
+```
+
+These markers let `apply` distinguish Adão-managed content from manual content.
+Generation is blocked when the scan is incomplete, package-manager evidence
+conflicts, or an unsupported `packageManager` declaration has no recognized
+lockfile to resolve it.
 
-### suggest
+### `suggest`
 
-Prepare a Markdown prompt that can be pasted into Codex or ChatGPT to improve `AGENTS.md`.
+`suggest` prepares a structured Markdown prompt from the local scan, current
+doctor result, deterministic generated draft, and a conservative selection of
+local evidence files.
 
 ```bash
-npm run dev -- suggest .
-npm run dev -- suggest . --json
+adao suggest .
+adao suggest . --json
 ```
 
-`suggest` does not call an AI service, does not use the OpenAI API, and does not send project files anywhere. It only uses local scan results, the current generated `AGENTS.md`, the current doctor validation result, and a conservative set of local evidence files.
+It does **not** call the OpenAI API, invoke an LLM, or send project files to any
+service. Adão only prints the prompt (or returns it as part of the JSON result).
+You may then give that prompt separately to Codex, ChatGPT, or another AI for
+review. Adão does not perform that review itself.
+
+The prompt tells the reviewer to use only the supplied evidence, preserve
+detected commands, avoid invented project details, and use TODOs where evidence
+is missing. Evidence files and total prompt evidence are size-limited, and
+truncation is marked in the prompt.
+
+### `apply`
+
+`apply` prepares the same deterministic content as `generate`, shows the
+proposed content or a diff, and asks for confirmation before writing. Use
+`--yes` only when non-interactive confirmation is intended.
 
-Use `generate` when you want Adao's deterministic local AGENTS.md draft. Use `suggest` when you want a structured prompt for a separate AI review while keeping Adao itself local-first and deterministic.
+```bash
+adao apply .
+adao apply . --yes
+```
 
-The prompt instructs the AI to use only provided evidence, preserve detected commands, avoid inventing project goals or architecture, and write TODOs when evidence is missing.
+Its update behavior depends on the existing file:
+
+- if `AGENTS.md` does not exist, Adão creates a marked file;
+- if valid Adão markers exist, it replaces only the managed region and
+  preserves content before and after it byte for byte;
+- if a legacy `AGENTS.md` has no markers, Adão warns that the whole file will be
+  replaced and that manual content will not remain in the active file. It asks
+  for confirmation and creates a backup before replacement;
+- malformed, duplicated, or incomplete markers are rejected.
+
+For replacements, Adão creates the first available numbered backup
+(`AGENTS.md.bak`, `AGENTS.md.bak.1`, and so on) without overwriting older
+backups. It writes the new content to a temporary file in the same directory,
+flushes and closes it, checks that `AGENTS.md` has not changed since the
+preview, then renames the temporary file over the target. This is an atomic
+replacement strategy on filesystems that provide atomic same-directory rename;
+it is not a claim of absolute atomicity across every filesystem or failure
+mode.
+
+The writer preserves the existing file's permission bits, rejects an
+`AGENTS.md` symbolic link, revalidates content before replacement to reduce the
+risk of overwriting concurrent edits, and removes its temporary file when an
+update fails. Unsafe or incomplete project evidence is rejected before the
+confirmation and write steps.
+
+## Safety guarantees
+
+- **Local-first:** scan, validation, generation, suggestion preparation, and
+  application run locally.
+- **No external upload:** Adão does not send project files to external services.
+- **Deterministic generation:** the same accepted evidence follows fixed local
+  rules; missing context becomes a TODO.
+- **Complete evidence required:** incomplete scans block `generate`, `suggest`,
+  and `apply`, and are errors in `doctor`.
+- **Manual content boundaries:** content outside valid Adão markers is preserved
+  byte for byte. Legacy unmarked files receive an explicit replacement warning
+  and a backup.
+- **Non-destructive backups:** existing backup names are never reused.
+- **Careful replacement:** temporary-file writing, same-directory rename,
+  permission preservation, symlink rejection, and concurrent-content checks
+  reduce write risk.
+- **No silent unsafe overwrite:** invalid markers, conflicting package-manager
+  evidence, incomplete scans, and detected concurrent changes abort the update.
+
+## How it works
+
+1. The filesystem walker skips common generated or vendor directories and
+   records scan completeness.
+2. The scanner validates relevant `package.json` fields and derives a bounded
+   set of facts from filenames, package metadata, README content, and directory
+   structure.
+3. `doctor` compares the current instructions with those facts using
+   conservative checks.
+4. `generate` turns accepted facts into a short marked baseline. `suggest`
+   packages that baseline and selected evidence into a prompt for an external
+   reviewer.
+5. `apply` previews the exact next file and uses the guarded write workflow
+   described above.
+
+Adão itself has no network or AI integration. Only the separately chosen tool
+that receives a `suggest` prompt would perform an AI review.
+
+## Current limitations
+
+- The current heuristics are initially optimized for Node.js and TypeScript
+  projects, although the scanner recognizes a limited set of other file
+  extensions and ecosystems.
+- Stack and tool detection is based on a defined package-dependency list; it
+  does not identify every framework or infer arbitrary architecture.
+- `AGENTS.md` validation is conservative and cannot fully understand natural
+  language or prove that instructions are semantically correct.
+- `suggest` selects a bounded set of conventional evidence files rather than
+  understanding the entire repository semantically.
+- There is no embedded LLM, GUI, plugin system, database, or automatic
+  project-wide semantic analysis.
+- `@laurowd/adao` is prepared for npm publication but is not published yet.
+
+## Development
+
+Install the locked dependencies and run the main checks:
 
-### apply
+```bash
+npm ci
+npm test
+npm run build
+npm audit
+```
 
-Generate the suggested `AGENTS.md`, show a diff when the file already exists, ask for confirmation, and create `AGENTS.md.bak` before overwriting.
+Package validation is available locally as well:
 
 ```bash
-npm run dev -- apply .
+npm pack --dry-run
+npm run test:package
 ```
 
-## Project layout
+`npm run test:package` builds a real tarball, installs it into a temporary
+project, verifies `adao --help`, `adao --version`, and `adao scan`, and checks
+that development-only files and dependencies are not shipped.
+
+The GitHub Actions workflow currently runs the test suite and build on Node.js
+18 and Node.js 22. A separate Node.js 22 packaging job runs `npm audit`, inspects
+an npm package dry run, then installs and executes the real tarball.
+
+## Project structure
 
 ```text
+.github/workflows/
+  ci.yml                    # Node 18/22 tests, build, audit, and package checks
+scripts/
+  clean.mjs                 # removes compiled output before builds
+  package-smoke.mjs         # packs, installs, and executes the real tarball
 src/
-  cli.ts
+  cli.ts                    # command dispatch, formatting, and exit behavior
+  cliArgs.ts                # strict command and flag parsing
+  packageVersion.ts         # reads the CLI version from package.json
   core/
-    scanProject.ts
-    detectStack.ts
-    readPackageJson.ts
-    validateAgents.ts
-    generateAgents.ts
-    suggestAgents.ts
-    diffAgents.ts
-    types.ts
+    applyAgents.ts          # managed regions, backups, and guarded writes
+    detectStack.ts          # language, tool, structure, and manager detection
+    diffAgents.ts           # line-oriented preview diff
+    generateAgents.ts       # deterministic managed AGENTS.md generation
+    readPackageJson.ts      # package metadata parsing and validation
+    scanProject.ts          # scan orchestration and completeness guards
+    suggestAgents.ts        # local evidence selection and prompt construction
+    types.ts                # shared domain types
+    validateAgents.ts       # doctor rules and status calculation
   utils/
-    fs.ts
-    paths.ts
-tests/
-  scanProject.test.ts
-  validateAgents.test.ts
-  generateAgents.test.ts
-  suggestAgents.test.ts
-  cli.test.ts
+    fs.ts                   # bounded filesystem traversal
+    paths.ts                # path normalization helpers
+tests/                      # unit and CLI workflow coverage
 ```
+
+## License
+
+[MIT License](LICENSE)
diff --git a/README.pt-BR.md b/README.pt-BR.md
new file mode 100644
index 0000000..0c8f287
--- /dev/null
+++ b/README.pt-BR.md
@@ -0,0 +1,355 @@
+# Adão
+
+[![Status da CI](https://github.com/Laurowd/Adao/actions/workflows/ci.yml/badge.svg)](https://github.com/Laurowd/Adao/actions/workflows/ci.yml)
+[![Licença MIT](https://img.shields.io/badge/licen%C3%A7a-MIT-blue.svg)](LICENSE)
+
+[English](README.md) | Português
+
+Adão é uma CLI local-first para projetos que usam `AGENTS.md`. Ela examina um
+projeto, verifica se suas instruções ainda correspondem às evidências locais,
+gera contexto determinístico, prepara um prompt estruturado para uma revisão
+separada por IA e aplica atualizações gerenciadas com segurança.
+
+## Por que o Adão existe
+
+Agentes de código dependem de instruções corretas sobre o projeto. Um
+`AGENTS.md` desatualizado, vago ou grande demais pode indicar comandos
+inexistentes, descrever a stack errada ou consumir contexto sem ajudar.
+
+O Adão transforma evidências já presentes em um repositório em um fluxo
+repetível: inspecionar o projeto, diagnosticar instruções suspeitas, gerar uma
+base conservadora, opcionalmente preparar as evidências para uma revisão externa
+por IA e atualizar apenas o conteúdo gerenciado pelo Adão quando os marcadores
+estão presentes.
+
+## Início rápido
+
+O Adão requer Node.js 18 ou mais recente. O pacote está preparado como
+`@laurowd/adao`, mas **ainda não foi publicado no npm**. Para usar a versão atual
+a partir de um checkout:
+
+```bash
+git clone https://github.com/Laurowd/Adao.git
+cd Adao
+npm ci
+npm run build
+node dist/cli.js --help
+```
+
+Os comandos planejados abaixo se aplicam somente **depois que o pacote for
+publicado**:
+
+```bash
+npm install -g @laurowd/adao
+npx @laurowd/adao --help
+```
+
+Os cinco comandos de projeto cobrem partes diferentes do fluxo:
+
+| Comando | Finalidade |
+| --- | --- |
+| `scan` | Inventariar evidências do projeto, como linguagens, scripts, ferramentas e estrutura. |
+| `doctor` | Verificar se o `AGENTS.md` atual ainda é consistente com as evidências detectadas. |
+| `generate` | Imprimir uma base determinística de `AGENTS.md` derivada de evidências locais. |
+| `suggest` | Montar um prompt estruturado para uma revisão separada por Codex, ChatGPT ou outra IA. |
+| `apply` | Visualizar e gravar com segurança o conteúdo gerenciado gerado. |
+
+A partir de um checkout de desenvolvimento:
+
+```bash
+npm run dev -- scan .
+npm run dev -- doctor .
+npm run dev -- generate .
+npm run dev -- suggest .
+npm run dev -- apply .
+```
+
+## Comandos
+
+O contrato atual da CLI é:
+
+```text
+adao scan <projectPath> [--json]
+adao doctor <projectPath> [--json]
+adao generate <projectPath>
+adao suggest <projectPath> [--json]
+adao apply <projectPath> [--yes]
+
+adao --help
+adao --version
+```
+
+`scan`, `doctor` e `suggest` aceitam saída JSON opcional. `apply` pede
+confirmação, exceto quando `--yes` é fornecido. Uso inválido termina com código
+`2`; falhas operacionais e um resultado de `doctor` com erros terminam com
+código `1`. Erros normais de uso e operação são concisos e não imprimem stack
+traces.
+
+Cada comando também possui ajuda específica, por exemplo
+`adao apply --help`.
+
+### `scan`
+
+`scan` lê a árvore do projeto e coleta evidências que incluem:
+
+- nome do projeto, descrição do pacote e resumo derivado localmente;
+- linguagens detectadas pelas extensões dos arquivos;
+- um conjunto conservador de frameworks e ferramentas detectados nos metadados
+  do pacote;
+- scripts do pacote e evidências do gerenciador de pacotes;
+- arquivos importantes e diretórios relevantes do projeto;
+- presença de `README.md`, metadados Git e `AGENTS.md`.
+
+A saída textual padrão resume o scan; `--json` expõe o resultado estruturado
+completo, incluindo os campos de descrição do pacote e resumo derivado.
+
+```bash
+adao scan .
+adao scan . --json
+```
+
+Por padrão, o scanner examina até 5.000 entradas do filesystem e informa quantas
+entradas inspecionou, se o limite foi atingido e quais caminhos não puderam ser
+lidos. As saídas textual e JSON expõem se o resultado está completo. Um scan
+truncado ou um erro bloqueante de filesystem torna as evidências incompletas;
+`doctor` relata essa condição como erro, enquanto `generate`, `suggest` e `apply`
+se recusam a continuar a partir de evidências parciais.
+
+A detecção é deliberadamente finita, não universal. A detecção de linguagens se
+baseia em extensões, e a de frameworks e ferramentas reconhece um conjunto
+definido de dependências de pacote.
+
+### `doctor`
+
+`doctor` valida o `AGENTS.md` atual contra as evidências detectadas no projeto e
+relata problemas como `error`, `warning` e `info`, seguidos de um status
+`healthy`, `needs attention` ou `broken`.
+
+```bash
+adao doctor .
+adao doctor . --json
+```
+
+As verificações atuais cobrem casos como:
+
+- `AGENTS.md` ausente;
+- comandos de pacote que não correspondem aos scripts disponíveis no
+  `package.json`;
+- comandos que usam um gerenciador de pacotes incompatível com as evidências
+  detectadas;
+- declarações de stack que parecem incompatíveis com o projeto detectado;
+- orientações vagas e tamanho excessivo do arquivo;
+- possível desatualização quando `README.md` ou `package.json` é mais recente;
+- conflito simples de gerenciador de pacotes com orientações globais em
+  `~/.codex/AGENTS.md`;
+- scan incompleto do projeto.
+
+A validação de stack é heurística e conservadora. Ela procura declarações
+assertivas de stack e evita tratar orientações negativas ou exemplos claramente
+hipotéticos como fatos do projeto. Um lockfile ficar mais recente não torna, por
+si só, o `AGENTS.md` desatualizado.
+
+### `generate`
+
+`generate` imprime um rascunho de `AGENTS.md` sem gravar arquivos ou chamar um
+serviço externo.
+
+```bash
+adao generate .
+```
+
+A geração é determinística e usa somente evidências locais, como metadados
+validados do `package.json`, `README.md`, scripts do pacote, stack detectada,
+evidências do gerenciador de pacotes e estrutura do projeto. A descrição do
+pacote tem prioridade no resumo do projeto; caso contrário, o Adão usa conteúdo
+útil do README. Quando as evidências disponíveis não são suficientes, ele
+registra um `TODO` explícito em vez de inventar objetivo, comando, stack ou
+arquitetura.
+
+O conteúdo gerado fica dentro de uma região gerenciada:
+
+```markdown
+<!-- adao:start -->
+
+<!-- conteúdo gerado -->
+
+<!-- adao:end -->
+```
+
+Esses marcadores permitem que `apply` diferencie o conteúdo gerenciado pelo Adão
+do conteúdo manual. A geração é bloqueada quando o scan está incompleto, as
+evidências de gerenciador de pacotes entram em conflito ou uma declaração
+`packageManager` não suportada não possui lockfile reconhecido que a resolva.
+
+### `suggest`
+
+`suggest` prepara um prompt estruturado em Markdown a partir do scan local, do
+resultado atual do doctor, do rascunho determinístico gerado e de uma seleção
+conservadora de arquivos de evidência locais.
+
+```bash
+adao suggest .
+adao suggest . --json
+```
+
+Ele **não** chama a OpenAI API, invoca um LLM nem envia arquivos do projeto para
+qualquer serviço. O Adão apenas imprime o prompt (ou o retorna como parte do
+resultado JSON). Depois, você pode fornecer esse prompt separadamente ao Codex,
+ChatGPT ou outra IA para revisão. O próprio Adão não executa essa revisão.
+
+O prompt instrui o revisor a usar somente as evidências fornecidas, preservar os
+comandos detectados, evitar detalhes inventados sobre o projeto e usar TODOs
+quando faltarem evidências. Os arquivos e o total de evidências do prompt possuem
+limites de tamanho, e os truncamentos são indicados no prompt.
+
+### `apply`
+
+`apply` prepara o mesmo conteúdo determinístico de `generate`, mostra o conteúdo
+proposto ou um diff e pede confirmação antes de gravar. Use `--yes` somente
+quando a confirmação não interativa for intencional.
+
+```bash
+adao apply .
+adao apply . --yes
+```
+
+O comportamento da atualização depende do arquivo existente:
+
+- se `AGENTS.md` não existe, o Adão cria um arquivo com marcadores;
+- se existem marcadores válidos do Adão, ele substitui somente a região
+  gerenciada e preserva byte a byte o conteúdo anterior e posterior;
+- se um `AGENTS.md` legado não possui marcadores, o Adão avisa que o arquivo
+  inteiro será substituído e que o conteúdo manual não permanecerá no arquivo
+  ativo. Ele pede confirmação e cria um backup antes da substituição;
+- marcadores malformados, duplicados ou incompletos são rejeitados.
+
+Nas substituições, o Adão cria o primeiro backup numerado disponível
+(`AGENTS.md.bak`, `AGENTS.md.bak.1` e assim por diante) sem sobrescrever backups
+anteriores. Ele grava o novo conteúdo em um arquivo temporário no mesmo
+diretório, sincroniza e fecha o arquivo, verifica se `AGENTS.md` não mudou desde
+a visualização e então renomeia o temporário sobre o destino. Essa é uma
+estratégia de substituição atômica em filesystems que oferecem rename atômico no
+mesmo diretório; não é uma afirmação de atomicidade absoluta em todo filesystem
+ou modo de falha.
+
+O escritor preserva os bits de permissão do arquivo existente, rejeita um
+`AGENTS.md` que seja link simbólico, revalida o conteúdo antes da substituição
+para reduzir o risco de sobrescrever edições concorrentes e remove seu arquivo
+temporário quando uma atualização falha. Evidências inseguras ou incompletas são
+rejeitadas antes das etapas de confirmação e escrita.
+
+## Garantias de segurança
+
+- **Local-first:** scan, validação, geração, preparação da sugestão e aplicação
+  são executados localmente.
+- **Nenhum envio externo:** o Adão não envia arquivos do projeto para serviços
+  externos.
+- **Geração determinística:** as mesmas evidências aceitas seguem regras locais
+  fixas; contexto ausente se torna um TODO.
+- **Evidência completa obrigatória:** scans incompletos bloqueiam `generate`,
+  `suggest` e `apply` e são erros no `doctor`.
+- **Limites do conteúdo manual:** o conteúdo fora de marcadores válidos do Adão
+  é preservado byte a byte. Arquivos legados sem marcadores recebem aviso
+  explícito de substituição e um backup.
+- **Backups não destrutivos:** nomes de backup existentes nunca são reutilizados.
+- **Substituição cuidadosa:** escrita em arquivo temporário, renomeação atômica
+  no mesmo diretório, preservação de permissões, rejeição de links simbólicos e
+  verificações de conteúdo concorrente reduzem o risco de escrita.
+- **Nenhuma substituição insegura silenciosa:** marcadores inválidos, evidências
+  conflitantes de gerenciador de pacotes, scans incompletos e alterações
+  concorrentes detectadas interrompem a atualização.
+
+## Como funciona
+
+1. O varredor do sistema de arquivos ignora diretórios comuns de artefatos gerados
+   ou dependências e registra se o scan está completo.
+2. O scanner valida os campos relevantes do `package.json` e deriva um conjunto
+   limitado de fatos a partir de nomes de arquivos, metadados do pacote, conteúdo
+   do README e estrutura de diretórios.
+3. `doctor` compara as instruções atuais com esses fatos usando verificações
+   conservadoras.
+4. `generate` transforma fatos aceitos em uma base curta e marcada. `suggest`
+   reúne essa base e evidências selecionadas em um prompt para um revisor externo.
+5. `apply` mostra o próximo arquivo exato e usa o fluxo de escrita protegido
+   descrito acima.
+
+O próprio Adão não possui integração de rede ou IA. Somente a ferramenta
+escolhida separadamente para receber um prompt de `suggest` executaria uma
+revisão por IA.
+
+## Limitações atuais
+
+- As heurísticas atuais são inicialmente otimizadas para projetos Node.js e
+  TypeScript, embora o scanner reconheça um conjunto limitado de outras
+  extensões e ecossistemas.
+- A detecção de stack e ferramentas se baseia em uma lista definida de
+  dependências de pacote; ela não identifica todo framework nem infere
+  arquiteturas arbitrárias.
+- A validação de `AGENTS.md` é conservadora e não consegue compreender por
+  completo linguagem natural ou provar que as instruções estão semanticamente
+  corretas.
+- `suggest` seleciona um conjunto limitado de arquivos de evidência convencionais
+  em vez de compreender semanticamente o repositório inteiro.
+- Não há LLM embutido, interface gráfica, sistema de plugins, banco de dados ou
+  análise semântica automática de todo o projeto.
+- `@laurowd/adao` está preparado para publicação no npm, mas ainda não foi
+  publicado.
+
+## Desenvolvimento
+
+Instale as dependências travadas e execute as principais verificações:
+
+```bash
+npm ci
+npm test
+npm run build
+npm audit
+```
+
+A validação do pacote também está disponível localmente:
+
+```bash
+npm pack --dry-run
+npm run test:package
+```
+
+`npm run test:package` gera um tarball real, instala-o em um projeto temporário,
+verifica `adao --help`, `adao --version` e `adao scan` e confirma que arquivos e
+dependências exclusivos de desenvolvimento não são distribuídos.
+
+O workflow do GitHub Actions atualmente executa a suíte de testes e o build no
+Node.js 18 e Node.js 22. Um job separado de empacotamento no Node.js 22 executa
+`npm audit`, inspeciona um dry run do pacote npm e então instala e executa o
+tarball real.
+
+## Estrutura do projeto
+
+```text
+.github/workflows/
+  ci.yml                    # testes Node 18/22, build, auditoria e pacote
+scripts/
+  clean.mjs                 # remove a saída compilada antes do build
+  package-smoke.mjs         # empacota, instala e executa o tarball real
+src/
+  cli.ts                    # despacho, formatação e códigos de saída da CLI
+  cliArgs.ts                # parsing estrito de comandos e flags
+  packageVersion.ts         # lê a versão da CLI no package.json
+  core/
+    applyAgents.ts          # regiões gerenciadas, backups e escrita protegida
+    detectStack.ts          # detecção de linguagem, ferramentas, estrutura e gerenciador
+    diffAgents.ts           # diff por linhas para visualização
+    generateAgents.ts       # geração determinística do AGENTS.md gerenciado
+    readPackageJson.ts      # parsing e validação dos metadados do pacote
+    scanProject.ts          # orquestração do scan e guardas de completude
+    suggestAgents.ts        # seleção de evidências e construção do prompt
+    types.ts                # tipos de domínio compartilhados
+    validateAgents.ts       # regras do doctor e cálculo do status
+  utils/
+    fs.ts                   # navegação limitada pelo filesystem
+    paths.ts                # utilitários de normalização de caminhos
+tests/                      # cobertura unitária e dos fluxos da CLI
+```
+
+## Licença
+
+[MIT License](LICENSE)
diff --git a/package.json b/package.json
index 80e11ba..0fd6378 100644
--- a/package.json
+++ b/package.json
@@ -21,7 +21,8 @@
   "type": "module",
   "files": [
     "dist/",
-    "README.md"
+    "README.md",
+    "README.pt-BR.md"
   ],
   "bin": {
     "adao": "dist/cli.js"
diff --git a/scripts/package-smoke.mjs b/scripts/package-smoke.mjs
index abd8ff5..3fb7115 100644
--- a/scripts/package-smoke.mjs
+++ b/scripts/package-smoke.mjs
@@ -145,7 +145,13 @@ function run(command, args, options) {
 }
 
 function assertPackageContents(files) {
-  const requiredFiles = ["README.md", "package.json", "dist/cli.js"];
+  const requiredFiles = [
+  "README.md",
+  "README.pt-BR.md",
+  "LICENSE",
+  "package.json",
+  "dist/cli.js"
+];
   const forbiddenPatterns = [
     /^(?:src|tests|scripts|coverage)\//,
     /^AGENTS\.md(?:\.bak(?:\.\d+)?)?$/,
@@ -160,12 +166,13 @@ function assertPackageContents(files) {
   }
 
   const unexpectedFile = files.find(
-    (file) =>
-      !file.startsWith("dist/") &&
-      file !== "README.md" &&
-      file !== "package.json" &&
-      !/^LICENSE(?:\.|$)/i.test(file)
-  );
+  (file) =>
+    !file.startsWith("dist/") &&
+    file !== "README.md" &&
+    file !== "README.pt-BR.md" &&
+    file !== "package.json" &&
+    !/^LICENSE(?:\.|$)/i.test(file)
+);
   const forbiddenFile = files.find((file) =>
     forbiddenPatterns.some((pattern) => pattern.test(file))
   );