# Desenvolvimento com IA/Agents

> O OonCore distribui documentação canônica versionada em .ooncore/ para que Codex, Claude, ChatGPT, Kimi, Manus e outros Agents codifiquem dentro dos contratos.

O OonCore foi desenhado para desenvolvimento assistido. A fonte de verdade operacional para Agents fica **dentro do pacote** `@oondemand/create-central-oon` e é copiada para cada App, sempre na versão instalada.

## O cache `.ooncore/`

```bash
npm run ooncore:docs        # sincroniza .ooncore/ com a versão instalada
npm run ooncore:docs:check  # valida versão e hashes
```

- `.ooncore/AGENTS.md` é a entrada canônica: roteia qualquer Agent para os contratos da versão instalada.
- `.ooncore/TASK_INDEX.md` organiza a documentação **por intenção** ("quero cadastrar e listar", "quero gerar PDF"…).
- `.ooncore/context.generated.md` é uma compilação opcional para consulta — não uma leitura obrigatória.
- O manifesto documental guarda hash de cada arquivo; `docs check` acusa qualquer edição manual.

> [!IMPORTANT]
> Versione `.ooncore/` junto com o código e os lockfiles. Não edite a pasta à mão. O `AGENTS.md` **da raiz** pertence ao seu projeto e nunca é sobrescrito.

## Guias distribuídos

| Guia | Quando usar |
|---|---|
| `AGENTS.md`, `OON_APP_AGENT_GUIDE.md`, `AGENT_WORKFLOW.md` | Entrada e roteiro curto |
| `TASK_INDEX.md`, `TASK_EXAMPLES.md` | Encontrar a API certa por tarefa |
| `PUBLIC_CONTRACTS.md`, `BACKEND_API.md`, `FRONTEND_API.md` | Assinaturas públicas |
| `BACKEND_DOMAIN_MANIFEST.md`, `BACKEND_PROCESS_MANIFEST.md` | Domínio e processo declarativos |
| `FRONTEND_CODE_FIRST.md`, `ADVANCED_UX_PATTERNS.md`, `DETAIL_MODAL_AND_RELATED_GRIDS.md` | Experiência |
| `RBAC_SECURITY.md`, `AUTH_ACTIVATION_RBAC.md`, `USERS_AND_ACCESS.md` | Segurança e acesso |
| `CAPABILITIES.md`, `TRANSACTIONAL_EMAIL.md`, `PDF_RENDERING.md`, `SECRETS.md` | Capabilities |
| `CORE_UPGRADE.md`, `APP_PACKAGING.md`, `TROUBLESHOOTING.md`, `ERRORS.md` | Operação |

## Roteiro recomendado para um Agent

1. **Gerar** a base oficial — nunca copiar outro App.
2. **Escolher a jornada** e consultar somente a linha correspondente do `TASK_INDEX.md`.
3. **Implementar** domínio e experiência pelos contratos públicos, preservando permissões, contexto e segredos.
4. **Validar** com `npm run check`, build do frontend e testes relevantes; provar a jornada pela UI/API.
5. **Publicar** pelo fluxo existente e registrar commit e evidência em Dev.

## Regras para Agents

- Use somente exports públicos; fontes internas e outros Apps não substituem contratos.
- Se faltar contrato, **registre a lacuna** com versão, tarefa e informação ausente. Continue as partes independentes e suspenda apenas a operação que não pode ser implementada com segurança. Não invente APIs.
- Preserve autenticação, autorização de backend, contexto autorizado, isolamento, auditoria e proteção de segredos. **POC reduz escopo funcional, não proteção.**
- Plataforma homologada: consuma identidade, acesso, tenancy, licenciamento e delivery; não reimplemente.
- Entregue uma jornada utilizável com página, navegação, endpoint e permissão. O perfil admin pode validar a POC.
- Relate separadamente **implementação, build, publicação e homologação** — são estados distintos.

## Exemplo de instrução para seu Agent

```md title="AGENTS.md (raiz do seu App)"
# Minha Central

- Leia `.ooncore/AGENTS.md` antes de alterar o código.
- Domínio: central de compras (fornecedores, pedidos, aprovações).
- Use admin para validar a POC; mantenha permissões no backend.
- Antes do PR: `npm run check` e `npm run build --prefix frontend`.
```

Fonte: https://sdk.oonapps.com/docs/introducao/desenvolvimento-com-agents