docs: consolidate agent instructions into AGENTS.md

AGENTS.md

@@ -4,8 +4,8 @@ This file is for coding agents working in this repository. Keep it practical:
 follow the project conventions, avoid speculative dependencies, and produce
 reproducible data work.
 
-For Claude Code / Cursor harness specifics (worktrees, ship routing), see
-[`CLAUDE.md`](CLAUDE.md).
+Harness specifics (worktrees, ship routing, `.venv` resolver) are in
+[Harness: ship, worktrees, commands](#harness-ship-worktrees-commands).
 
 ## Agent skills
 
@@ -24,7 +24,7 @@ duplicated in this repo; use the installed host skills.
 ## Project baseline
 
 - Implementation checkout: a dedicated **worktree**, never the root checkout
-  and never `main`. Root/`main` are inspect-only (see `CLAUDE.md`).
+  and never `main`. Root/`main` are inspect-only (see [Worktree Policy](#worktree-policy)).
 - Project name: Dados Financeiros Abertos.
 - Distribution/package slug: `openfindata`.
 - Import package and CLI remain `findata` for compatibility.
@@ -171,3 +171,73 @@ matrix, templates, and examples of source/technical lines.
 - Do not tag a release until tests and adversarial review are clean.
 - When handing off to another agent, summarize: what changed, why, verification,
   risks, and the next executable step.
+
+## Harness: ship, worktrees, commands
+
+### Ship / PR
+
+Use a skill **`openfindata-ship`** como primeira ação sempre que o request for
+publicar código: commit, push, abrir/atualizar PR, ready-for-review, ou
+endereçar comentários cujo resultado mude código.
+
+Fonte canônica (somente no repo):
+
+```text
+docs/agents/openfindata-ship/SKILL.md
+```
+
+Inspeção read-only de PR pode usar `gh` direto. No momento em que edição,
+push ou criação de PR entram em cena, volte para `openfindata-ship`.
+
+PyPI e tags de release exigem aprovação humana explícita: ship nunca publica
+pacote sozinho.
+
+### Worktree Policy
+
+#### Branch naming
+
+- Claude / Cursor: `claude/<feature-slug>` ou `cursor/<feature-slug>`
+- Codex: `codex/<feature-slug>`
+- Slug descreve a feature (ex.: `agent-quality-workflows`), não categoria genérica
+
+#### Estrutura
+
+- `.claude/worktrees/*`: worktrees do Claude Code
+- `$HOME/.cursor/worktrees/*`: worktrees do Cursor
+- `.worktrees/codex-*`: worktrees do Codex
+- **Root checkout = inspeção apenas.** Nunca implementar, commitar ou fazer push do root.
+- **`main` = integração;** nunca mutar código diretamente nela.
+
+Depois de pull/merge que altere `.githooks/*` ou `scripts/git/guardrails.sh`,
+rode `bash scripts/git/install-hooks.sh` antes de confiar nos hooks locais.
+
+#### Bypass (emergência)
+
+Só com intenção explícita do operador:
+
+```bash
+OPENFINDATA_GUARDRAILS_BYPASS=1 git commit ...
+```
+
+Não use bypass como atalho de rotina.
+
+### Comandos úteis
+
+```bash
+bash scripts/git/install-hooks.sh
+bash scripts/ship/preflight.sh
+bash docs/agents/openfindata-ship/scripts/readiness.sh
+.venv/bin/findata serve --reload   # ou scripts/dev_server.sh
+```
+
+#### Python / `.venv` (contrato único)
+
+Resolver usado por `scripts/ship/preflight.sh` e `scripts/git/guardrails.sh`:
+
+1. `<worktree>/.venv/bin/python` se existir;
+2. senão `<repo-root>/.venv/bin/python` (venv criado no clone raiz);
+3. senão `python3` no `PATH`.
+
+Comandos documentados como `.venv/bin/...` significam “o interpretador desse
+resolver”, não “somente um `.venv` local à worktree”. Preferência: criar o
+venv no root uma vez (`CONTRIBUTING.md`) e reutilizá-lo nas worktrees.

CONTRIBUTING.md

@@ -37,7 +37,7 @@ permitidas.
 | Claude / Cursor | `claude/<slug>` ou `cursor/<slug>` | `.claude/worktrees/*` ou `$HOME/.cursor/worktrees/*` |
 | Codex | `codex/<slug>` | `.worktrees/codex-*` |
 
-Ver [`CLAUDE.md`](CLAUDE.md) e [`docs/agents/openfindata-ship/`](docs/agents/openfindata-ship/).
+Ver [`AGENTS.md`](AGENTS.md#harness-ship-worktrees-commands) e [`docs/agents/openfindata-ship/`](docs/agents/openfindata-ship/).
 
 Gate local canônico antes de publicar:
 

docs/agents/domain.md

@@ -13,7 +13,6 @@ antes de explorar ou alterar o código.
 - **[`docs/RESOLVER.md`](../RESOLVER.md)** — registry/resolver para lookups de agente.
 - **[`docs/CHART_STANDARDS.md`](../CHART_STANDARDS.md)** — contrato informacional de gráficos.
 - **`docs/source-notes/`** — notas por fonte (`basedosdados`, `yahoo`, `advfn`, …).
-- **[`CLAUDE.md`](../../CLAUDE.md)** — worktrees e roteamento de ship (Claude/Cursor).
 
 Se um documento **obrigatório de política/segurança** estiver ausente
 (`SOURCES_WITH_AUTH.md`, `MCP_SURFACE.md`, `AGENTS.md`), pare com
@@ -26,7 +25,6 @@ canônica mais próxima em silêncio. Não invente glossário paralelo.
 ```text
 /
 ├── AGENTS.md
-├── CLAUDE.md
 ├── CONTRIBUTING.md
 ├── src/findata/
 │   ├── sources/<source>/

docs/agents/orientation.md

@@ -10,7 +10,7 @@ mortos, fronteira atual, openfindata, findata.
 
 - Produto e escopo: [`README.md`](../../README.md), [`MANIFESTO.txt`](../../MANIFESTO.txt).
 - Convenções universais de código e gates: [`AGENTS.md`](../../AGENTS.md).
-- Harness Claude (worktrees, ship): [`CLAUDE.md`](../../CLAUDE.md).
+- Harness (worktrees, ship): [`AGENTS.md`](../../AGENTS.md#harness-ship-worktrees-commands).
 - Contribuição humana: [`CONTRIBUTING.md`](../../CONTRIBUTING.md).
 - Superfície MCP curada: [`docs/MCP_SURFACE.md`](../MCP_SURFACE.md).
 - Padrões de gráfico: [`docs/CHART_STANDARDS.md`](../CHART_STANDARDS.md).
@@ -30,7 +30,7 @@ mortos, fronteira atual, openfindata, findata.
 | Code mode no MCP? | Opt-in via `FINDATA_MCP_CODE_MODE=1`; off por default | `docs/MCP_SURFACE.md`, `mcp_app.py` |
 | Charts: quais deps de plot? | Não adicionar matplotlib/pandas/plotly etc. só para gráfico | `AGENTS.md`, `docs/CHART_STANDARDS.md` |
 | Publicar no PyPI? | Só com aprovação humana explícita | `AGENTS.md` |
-| Onde agentes implementam? | Worktree dedicada; root/`main` são inspect-only | `CLAUDE.md`, `docs/agents/openfindata-ship/` |
+| Onde agentes implementam? | Worktree dedicada; root/`main` são inspect-only | `AGENTS.md`, `docs/agents/openfindata-ship/` |
 
 ## O que morreu e por quê
 

docs/agents/quality.md

@@ -13,7 +13,7 @@ bash scripts/ship/preflight.sh
 
 Equivalente expandido (mesmo conjunto que o preflight `--push`). Interpretador:
 worktree `.venv`, senão `.venv` na raiz do repo comum, senão `python3` — ver
-`CLAUDE.md` § Python / `.venv`.
+`AGENTS.md` § Python / `.venv`.
 
 ```bash
 # Prefer: bash scripts/ship/preflight.sh