@oondemand/create-central-oon 0.6.2 → 0.6.4

package/README.md

@@ -1,16 +1,14 @@
 # @oondemand/create-central-oon
 
-Gerador estrutural de Apps Oon. Ele cria backend e frontend code-first prontos
-para consumir `@oondemand/oon-core-back` e `@oondemand/oon-core-front`.
+Gerador estrutural de Apps Oon. Ele cria backend e frontend code-first prontos para consumir `@oondemand/oon-core-back` e `@oondemand/oon-core-front` e inclui a documentação pública versionada necessária para Agents.
 
 ## Uso
 
 ```bash
-npx create-central-oon central-transtour
+npx --yes --package @oondemand/create-central-oon@0.6 create-central-oon central-exemplo
 ```
 
-O gerador possui uma única base `_base`. Não há seleção ou catálogo de
-templates funcionais. O binário também responde por `scaffold-central-oon`.
+O gerador possui uma única base `_base`. Não há seleção ou catálogo de templates funcionais. O binário também responde por `scaffold-central-oon`.
 
 ## Contrato `central.app.json`
 
@@ -22,8 +20,11 @@ templates funcionais. O binário também responde por `scaffold-central-oon`.
   "name": "Central Exemplo",
   "slug": "central-exemplo",
   "appKind": "member-central",
-  "accessMode": "private",
-  "authorization": { "mode": "tenant_members" },
+  "tenancyModel": "single_tenant",
+  "availability": "licensed",
+  "accessMode": "explicit_users",
+  "authorizationMode": "rbac",
+  "deploymentMode": "dedicated",
   "modules": {
     "collections": false,
     "documents": false,
@@ -33,28 +34,30 @@ templates funcionais. O binário também responde por `scaffold-central-oon`.
   },
   "capabilities": [],
   "compatibility": {
-    "core": {
-      "minVersion": "0.6.0",
-      "maxVersionExclusive": "0.7.0"
-    }
+    "core": { "minVersion": "0.6.0" }
   }
 }
 ```
 
-O manifesto contém identidade, política de acesso, capacidades de plataforma e
-compatibilidade. Rotas, menus, páginas, componentes, layouts e temas ficam no
-código do frontend, para qualquer `appKind`.
+O manifesto contém identidade, política de acesso, capabilities funcionais e compatibilidade. Dependências de infraestrutura de publicação ficam em `oon.deploy.json`. Rotas, menus, páginas, componentes, layouts e temas ficam no código do frontend.
 
 ## Estrutura gerada
 
 ```txt
 <app>/
+├── .ooncore/
+│   ├── AGENTS.md
+│   ├── CODEX.md
+│   ├── manifest.json
+│   ├── context.generated.md
+│   └── docs/
 ├── central.app.json
+├── oon.deploy.json
 ├── package.json
 ├── backend/
 │   ├── central.config.js
-│   ├── central.domain.json
-│   └── src/{validations,triggers,hooks,mappings,rules}/
+│   ├── central.manifest.json
+│   └── src/{models,validations,triggers,hooks,mappings,rules,routes,services}/
 └── frontend/
     └── src/
         ├── main.tsx
@@ -65,29 +68,28 @@ código do frontend, para qualquer `appKind`.
         └── layouts/
 ```
 
-O bootstrap gerado chama `startOonApp(app)`. A composição é feita com
-`defineOonApp`, `defineOonRoutes` e `defineOonNavigation`.
+Um domínio declarativo pode adicionar `backend/central.domain.json` conforme seu contrato; ele não faz parte da base neutra. O bootstrap chama `startOonApp(app)` e a composição usa `defineOonApp`, `defineOonRoutes` e `defineOonNavigation`.
 
-## Conformidade
+## Contrato para Agents
 
-```bash
-npm run ooncore:conformance
-npx create-central-oon conformance --json
-```
+A documentação em `.ooncore/` é autocontida. Um Agent deve conseguir criar e customizar o App sem ler o monorepo do OonCore, `node_modules`, outros Apps ou documentação privada.
 
-A verificação exige schema v2 e bootstrap code-first, protege rotas reservadas,
-guards de segurança e imports internos, e rejeita código remoto, segredos no
-bundle e dependências fora do frontend.
+Comece por:
 
-## Documentação
+1. `.ooncore/AGENTS.md`;
+2. `.ooncore/docs/OON_APP_AGENT_GUIDE.md`;
+3. `.ooncore/docs/CAPABILITIES.md`;
+4. o contrato dedicado apontado para a tarefa.
 
-O pacote distribui documentação canônica em `docs/`. O comando abaixo atualiza
-o cache `.ooncore/` usado por ferramentas de desenvolvimento:
+Se faltar informação pública, registre a lacuna; não deduza APIs por implementação interna.
+
+## Conformidade
 
 ```bash
-npm run ooncore:docs
 npm run ooncore:docs:check
+npm run ooncore:conformance
+npm run check
+npm test
 ```
 
-Consulte `docs/FRONTEND_CODE_FIRST.md` para o contrato completo.
-
+A verificação exige schema v2 e bootstrap code-first, protege rotas reservadas, guards de segurança e imports internos, e rejeita código remoto, segredos no bundle e dependências fora do frontend.

package/docs/AGENTS.md

@@ -1,15 +1,22 @@
 # OonCore — entrada canônica para IA/Agents
 
-Este arquivo é o contrato inicial neutro para Codex, ChatGPT, Kimi, Manus e outros Agents que alterem uma Central Oon.
+Este arquivo é o contrato inicial neutro para Codex, ChatGPT, Kimi, Manus e outros Agents que criem ou alterem uma Central Oon.
+
+## Contrato de autonomia
+
+O Agent deve trabalhar em modo **closed-book**: a árvore do App gerado, incluindo `.ooncore/`, é suficiente. Código-fonte do OonCore, `node_modules`, repositórios de outros Apps e documentação privada não são contratos de extensão e não devem ser usados para descobrir comportamento suportado.
+
+Se a documentação distribuída não responder à tarefa, pare e registre a lacuna. Não invente API nem contorne a fronteira pública.
 
 ## Ordem de leitura
 
 1. Leia primeiro o `AGENTS.md` da raiz do projeto consumidor, quando existir.
 2. Confirme `schemaVersion`, `version`, `docsHash` e `entrypointsHash` em `.ooncore/manifest.json`.
 3. Rode `npm run ooncore:docs:check`; se falhar, rode `npm run ooncore:docs` e verifique novamente.
-4. Consulte `docs/CAPABILITIES.md` antes de criar código.
-5. Leia os contratos de backend, frontend, runtime ou RBAC indicados abaixo.
-6. Leia a documentação de domínio do projeto consumidor.
+4. Leia [OON_APP_AGENT_GUIDE.md](OON_APP_AGENT_GUIDE.md).
+5. Consulte [CAPABILITIES.md](CAPABILITIES.md) antes de criar código.
+6. Leia os contratos de backend, frontend, runtime, RBAC ou capability indicados abaixo.
+7. Leia a documentação de domínio do projeto consumidor.
 
 O `AGENTS.md` da raiz pertence ao projeto e nunca pode ser sobrescrito pelo scaffold ou pelo sync do Core.
 
@@ -17,13 +24,16 @@ O `AGENTS.md` da raiz pertence ao projeto e nunca pode ser sobrescrito pelo scaf
 
 | Tarefa | Leitura obrigatória |
 |---|---|
-| Domínio, models, validações e fórmulas | `BACKEND_API.md`, `BACKEND_DOMAIN_MANIFEST.md`, `BACKEND_PATTERNS.md`, `REACTIVE_DOMAIN_FORMULAS.md` |
-| CRUD, metadata e UI | `METADATA_CRUD_UI.md`, `FRONTEND_API.md`, `FRONTEND_CODE_FIRST.md` |
-| Auth, ativação, tenant ou permissões | `AUTH_ACTIVATION_RBAC.md`, `RBAC_SECURITY.md`, `DO_AND_DONT.md` |
-| Execução local | `RUNTIME_MODES.md`, `LOCAL_DEVELOPMENT.md`, `LOCAL_SECURITY_BOUNDARY.md` |
-| Rotas, hooks, jobs e filas | `ROUTES_HOOKS_WORKERS.md`, `BACKEND_PATTERNS.md` |
-| Upgrade do Core | `CORE_UPGRADE.md`, `TESTING_CONFORMANCE.md`, `releases/0.6.0.md` |
-| UX avançada | `ADVANCED_UX_PATTERNS.md`, `DETAIL_MODAL_AND_RELATED_GRIDS.md`, `PORTAL_COCKPIT_PATTERNS.md` |
+| Criar um App ou definir onde customizar | [OON_APP_AGENT_GUIDE.md](OON_APP_AGENT_GUIDE.md), [CAPABILITIES.md](CAPABILITIES.md) |
+| Domínio, models, validações e fórmulas | [BACKEND_API.md](BACKEND_API.md), [BACKEND_DOMAIN_MANIFEST.md](BACKEND_DOMAIN_MANIFEST.md), [BACKEND_PATTERNS.md](BACKEND_PATTERNS.md), [REACTIVE_DOMAIN_FORMULAS.md](REACTIVE_DOMAIN_FORMULAS.md) |
+| CRUD, metadata e UI | [METADATA_CRUD_UI.md](METADATA_CRUD_UI.md), [FRONTEND_API.md](FRONTEND_API.md), [FRONTEND_CODE_FIRST.md](FRONTEND_CODE_FIRST.md) |
+| Auth, ativação, tenant ou permissões | [AUTH_ACTIVATION_RBAC.md](AUTH_ACTIVATION_RBAC.md), [RBAC_SECURITY.md](RBAC_SECURITY.md), [DO_AND_DONT.md](DO_AND_DONT.md) |
+| Renderizar, visualizar ou baixar PDF | [PDF_RENDERING.md](PDF_RENDERING.md), [BACKEND_API.md](BACKEND_API.md), [FRONTEND_API.md](FRONTEND_API.md) |
+| Configurar templates ou enviar e-mail | [TRANSACTIONAL_EMAIL.md](TRANSACTIONAL_EMAIL.md), [RBAC_SECURITY.md](RBAC_SECURITY.md) |
+| Execução local | [RUNTIME_MODES.md](RUNTIME_MODES.md), [LOCAL_DEVELOPMENT.md](LOCAL_DEVELOPMENT.md), [LOCAL_SECURITY_BOUNDARY.md](LOCAL_SECURITY_BOUNDARY.md) |
+| Rotas, hooks, jobs e filas | [ROUTES_HOOKS_WORKERS.md](ROUTES_HOOKS_WORKERS.md), [BACKEND_PATTERNS.md](BACKEND_PATTERNS.md) |
+| Upgrade do Core | [CORE_UPGRADE.md](CORE_UPGRADE.md), [TESTING_CONFORMANCE.md](TESTING_CONFORMANCE.md), [releases/0.6.0.md](releases/0.6.0.md) |
+| UX avançada | [ADVANCED_UX_PATTERNS.md](ADVANCED_UX_PATTERNS.md), [DETAIL_MODAL_AND_RELATED_GRIDS.md](DETAIL_MODAL_AND_RELATED_GRIDS.md), [PORTAL_COCKPIT_PATTERNS.md](PORTAL_COCKPIT_PATTERNS.md) |
 
 ## Fronteira obrigatória
 
@@ -43,4 +53,4 @@ npm run check
 npm test
 ```
 
-Se um contrato público exigir leitura do repositório privado do OonCore, registre a lacuna: a documentação distribuída está incompleta.
+Uma entrega que depende da leitura de fonte privada ou de outro App não está concluída: registre a lacuna na documentação distribuída.

package/docs/AGENT_WORKFLOW.md

@@ -1,13 +1,20 @@
 # Fluxo de trabalho para Agents
 
-1. **Descobrir:** leia `AGENTS.md`, manifesto documental e `CAPABILITIES.md`.
-2. **Classificar:** separe contrato do Core, domínio da Central e recurso exclusivo da plataforma.
-3. **Escolher extensão:** manifesto → validation/trigger/hook/mapping → renderer/rota pequena → código customizado somente se necessário.
-4. **Implementar:** use exports públicos; preserve segurança, tenant, auditoria e idempotência.
-5. **Executar local:** `npm run dev`, sem cadastro ou conexão com a plataforma.
-6. **Validar:** docs check, conformance, testes, typecheck e provas específicas do projeto.
-7. **Relatar:** arquivos, contratos usados, riscos, limitações e evidências.
+1. **Gerar:** para um App novo, siga [OON_APP_AGENT_GUIDE.md](OON_APP_AGENT_GUIDE.md) e confirme que `.ooncore/` foi criada.
+2. **Descobrir:** leia `AGENTS.md`, o manifesto documental e [CAPABILITIES.md](CAPABILITIES.md).
+3. **Classificar:** separe contrato do Core, domínio da Central e recurso exclusivo da plataforma.
+4. **Escolher extensão:** manifesto → validation/trigger/hook/mapping → renderer/rota pequena → código customizado somente se necessário.
+5. **Implementar:** use exports públicos documentados; preserve segurança, tenant, auditoria e idempotência.
+6. **Executar local:** `npm run dev`, sem cadastro ou conexão com a plataforma; capabilities de plataforma falham fechado.
+7. **Validar:** docs check, conformance, testes, typecheck e provas específicas do projeto.
+8. **Relatar:** arquivos, contratos usados, riscos, limitações e evidências.
+
+## Regra closed-book
+
+Mantenha os três pacotes OonCore na linha 0.6.x declarada pelo App e sincronize `.ooncore` após qualquer atualização.
+
+Trabalhe somente com o App e sua `.ooncore/`. Não leia fonte privada, `node_modules` ou outros Apps para descobrir como usar o Core. Se faltar assinatura, declaração, exemplo, erro ou limite necessário, interrompa essa parte e registre a lacuna documental.
 
 Prompt operacional:
 
-> Atualize os três pacotes OonCore para a linha 0.6.x, preserve o domínio e o AGENTS.md do projeto, sincronize `.ooncore`, consulte os contratos públicos de back e front, use apenas extensões suportadas, execute os gates e homologue em `127.0.0.1` sem conexão com a plataforma. Não crie autenticação, ativação, RBAC, CRUD, shell ou infraestrutura paralelos.
+> Crie ou atualize o Oon App usando exclusivamente a documentação versionada em `.ooncore`. Preserve o domínio e o AGENTS.md do projeto, consulte o catálogo e os contratos públicos de back, front e capabilities, use apenas extensões suportadas, execute os gates e homologue em `127.0.0.1` sem conexão com a plataforma. Não leia fonte privada ou outros Apps e não crie autenticação, ativação, RBAC, CRUD, shell ou infraestrutura paralelos.

package/docs/BACKEND_API.md

@@ -29,8 +29,16 @@ Erros de manifesto carregam `code`, `statusCode` e `issues[]` com `path` e `mess
 
 ## Capabilities
 
-- `capabilities`, `PdfRenderingError`, `TransactionalEmailError`.
-- `operationalRequestHeaders(options)`: headers de identidade do Deployment. Retorna `LOCAL_OPERATION_NOT_SUPPORTED` no runtime local; nunca improvise identidade local.
+O namespace público `capabilities` contém:
+
+- `capabilities.pdf.render(input, context): Promise<Buffer>`; contrato completo em [PDF_RENDERING.md](PDF_RENDERING.md);
+- alias compatível `capabilities.pdfRendering.render`;
+- `capabilities.transactionalEmail.send(input, context)` e operações administrativas; contrato completo em [TRANSACTIONAL_EMAIL.md](TRANSACTIONAL_EMAIL.md);
+- `PdfRenderingError` e `TransactionalEmailError` para normalização específica.
+
+O App nunca configura URL, credencial interna ou implementação de uma capability. A única exceção é a injeção de dublês documentada para testes automatizados.
+
+`operationalRequestHeaders(options)` produz headers de identidade do Deployment. Retorna `LOCAL_OPERATION_NOT_SUPPORTED` no runtime local; nunca improvise identidade local.
 
 ## Runtime local
 

package/docs/CAPABILITIES.md

@@ -1,23 +1,23 @@
 # Catálogo de capacidades do OonCore
 
-Consulte este catálogo antes de criar infraestrutura ou componentes customizados.
+Consulte este catálogo antes de criar infraestrutura ou componentes customizados. Para capabilities nativas, o guia dedicado é leitura obrigatória.
 
 | Capacidade | Backend | Frontend | Declaração/extensão | Local | Plataforma |
 |---|---|---|---|---|---|
-| Models e CRUD | `defineModel`, domain manifest, `/core/*` | `CoreCollection`, hooks de API | `central.domain.json`, composição code-first | Sim | Sim |
+| Models e CRUD | `defineModel`, domain manifest, `/core/*` | `CoreCollection`, hooks de API | `central.domain.json` ou composição code-first | Sim | Sim |
 | Metadata | registry e `/core/metadata` | `useCoreMetadata`, renderers | models/domain manifest | Sim | Sim |
 | Validações e fórmulas | `defineValidation`, domain rules | prévia reativa | domain manifest/validation | Sim | Sim |
-| Esteiras | process manifest/runtime | `CorePipeline` | `central.process.json`, UI manifest | Sim | Sim |
+| Esteiras | process manifest/runtime | `CorePipeline` | `central.process.json`, UI code-first | Sim | Sim |
 | Documentos | `defineDocument` | `CoreDocument` | UI/domain manifest | Sim | Sim |
-| Dashboards | agregações e rotas | `CoreDashboard` | UI manifest | Sim | Sim |
+| Dashboards | agregações e rotas | `CoreDashboard` | UI code-first | Sim | Sim |
 | RBAC | policy, middleware e `requirePermission` | `PermissionGate`, `can` | `central.app.json` | Simulação declarada | Identidade real |
 | Tenant e escopo | access context e scope helpers | `TenantProvider` | `central.app.json` | Contexto técnico | Contexto autorizado |
 | Auditoria | CRUD e request context | headers do SDK | automática/extensão | Local | Operacional |
 | Rotas customizadas | `defineRoutes` | página/ação declarada | `backend/src/routes` | Sim | Sim |
 | Jobs e workers | process workers | status operacional | manifestos/hooks | Sim | Sim |
-| E-mail transacional | capability nativa | `CoreTransactionalEmail` | capability settings | Dublê/local | Provider configurado |
-| PDF | capability nativa | consumo por ação | capability contract | Dublê/local | Provider configurado |
+| E-mail transacional | `capabilities.transactionalEmail` | `CoreTransactionalEmail` | [TRANSACTIONAL_EMAIL.md](TRANSACTIONAL_EMAIL.md) | Fail-closed/dublê de teste | Implementação resolvida pelo Core |
+| PDF | `capabilities.pdf.render` | `useOonApi`/download | [PDF_RENDERING.md](PDF_RENDERING.md) | Fail-closed/dublê de teste | Implementação resolvida pelo runtime |
 | Publicação/promoção | contratos de delivery | indisponível no App | CLI/ponte pública | Não | Sim |
 | Runtime local | sessão e guardas locais | bootstrap/cookie/banner | `OON_RUNTIME_MODE=local` | Sim | Não aplicável |
 
-Para cada capacidade, use o manifesto quando houver contrato declarativo; use código da Central apenas em pontos de extensão documentados.
+Para cada capacidade, use o manifesto quando houver contrato declarativo e código da Central apenas nos pontos de extensão documentados. Se uma capability não possuir guia dedicado suficiente, registre uma lacuna; não descubra o contrato lendo fonte privada ou outro repositório.

package/docs/CHECKLIST_IMPLEMENTACAO.md

@@ -2,11 +2,14 @@
 
 Use este checklist antes de concluir qualquer tarefa de codificação em uma Central Oon.
 
-## Contexto
+## Contexto e documentação
 
 - [ ] Rodei `npm run ooncore:docs:check`.
 - [ ] Rodei `npm run ooncore:docs` se havia documentação desatualizada.
-- [ ] Li `.ooncore/context.generated.md`.
+- [ ] Li `.ooncore/AGENTS.md` e o guia de autoria.
+- [ ] Consultei o catálogo e o contrato dedicado de cada capability usada.
+- [ ] Trabalhei somente com a árvore do App e `.ooncore/`, sem fonte privada, `node_modules` ou outros Apps.
+- [ ] Registrei qualquer lacuna em vez de inventar API ou infraestrutura.
 - [ ] Entendi qual recurso do Core já resolve parte da necessidade.
 
 ## Backend
@@ -15,27 +18,34 @@ Use este checklist antes de concluir qualquer tarefa de codificação em uma Cen
 - [ ] Evitei recriar CRUD.
 - [ ] Validei entrada.
 - [ ] Validei permissão no backend.
-- [ ] Tratei erros.
-- [ ] Não hardcodei segredos.
-- [ ] Mantive rastreabilidade.
+- [ ] Propaguei tenant, correlação, cancelamento e idempotência quando aplicáveis.
+- [ ] Tratei erros pelo contrato público.
+- [ ] Não hardcodei segredos, endpoints internos ou implementations.
+- [ ] Mantive rastreabilidade sem registrar conteúdo sensível.
 
 ## Frontend
 
 - [ ] Defini o App com `defineOonApp` e `startOonApp`.
 - [ ] Reutilizei shell, guards, primitives e padrões públicos do Core.
 - [ ] Mantive rotas, navegação, páginas, layouts e temas no código do App.
+- [ ] Usei `useOonApi` para chamadas autenticadas e respostas binárias.
 - [ ] Não coloquei regra crítica apenas no frontend.
 
-## Integrações
+## Integrações e capabilities
 
-- [ ] Usei camada de integração/conector.
-- [ ] Modelei mapping.
-- [ ] Registrei status de integração.
-- [ ] Normalizei erros externos.
+- [ ] Fiz a declaração no manifesto indicado pelo guia.
+- [ ] Usei camada de integração/capability pública.
+- [ ] Modelei mapping e status operacional quando necessário.
+- [ ] Normalizei erros externos e respeitei `retryable`.
+- [ ] O runtime local falha fechado ou usa dublê somente no teste.
 - [ ] Não expus credenciais.
 
 ## Entrega
 
+- [ ] `npm run ooncore:docs:check` passou.
+- [ ] `npm run ooncore:conformance` passou.
+- [ ] `npm run check` e `npm test` passaram.
+- [ ] Provei o fluxo específico do usuário.
 - [ ] A Central continua atualizável com novas versões do Core.
 - [ ] A alteração é pequena, coesa e aderente à arquitetura.
-- [ ] O comportamento esperado está documentado no README ou no próprio módulo quando necessário.
+- [ ] O comportamento específico do App está documentado sem duplicar contrato do Core.

package/docs/OON_APP_AGENT_GUIDE.md

@@ -0,0 +1,72 @@
+# Criar e customizar um Oon App com um Agent
+
+Este é o roteiro canônico de autoria. O contrato de aceite é **closed-book**: o Agent recebe somente a árvore do App gerado, incluindo `.ooncore/`, e não precisa consultar o código-fonte do OonCore, repositórios de outros Apps ou documentação privada.
+
+## 1. Gerar a base
+
+Em um diretório vazio:
+
+```bash
+npx --yes --package @oondemand/create-central-oon@0.6 create-central-oon meu-app --no-install
+cd meu-app
+npm install
+npm run ooncore:docs:check
+```
+
+O gerador cria backend, frontend, manifestos, gates e a documentação versionada em `.ooncore/`. Não copie arquivos de outro App para iniciar uma Central.
+
+## 2. Ler antes de alterar
+
+1. Leia `.ooncore/AGENTS.md`.
+2. Confira `.ooncore/manifest.json` e rode `npm run ooncore:docs:check`.
+3. Consulte [CAPABILITIES.md](CAPABILITIES.md).
+4. Abra somente os contratos indicados para a tarefa.
+5. Leia o `AGENTS.md` da raiz, quando o projeto possuir regras próprias.
+
+Se a resposta não estiver nesses arquivos, pare e registre uma lacuna documental. Não deduza contrato lendo `node_modules`, `src/` privado ou outros repositórios.
+
+## 3. Separar os contratos
+
+| Necessidade | Local correto |
+|---|---|
+| Identidade, tipo do App, tenant, acesso, módulos e RBAC | `central.app.json` |
+| Recursos exigidos do ambiente de publicação | `oon.deploy.json` |
+| Models e regras de domínio | `backend/src` ou `backend/central.domain.json`, quando o contrato declarativo for adotado |
+| Rotas e serviços específicos | `backend/src/routes` e `backend/src/services` |
+| Rotas, navegação, páginas, tema e experiência | `frontend/src/app`, `frontend/src/pages` e `frontend/src/components` |
+| Auth, ativação, shell, CRUD, metadata e infraestrutura | OonCore; não reimplementar |
+
+`central.app.json` e `oon.deploy.json` têm finalidades diferentes. Uma capability funcional do App pode exigir declaração no primeiro; uma dependência de infraestrutura, como renderização de PDF, é declarada no segundo. Siga o guia da capability.
+
+## 4. Customizar
+
+- Domínio: use [BACKEND_API.md](BACKEND_API.md), [BACKEND_DOMAIN_MANIFEST.md](BACKEND_DOMAIN_MANIFEST.md) e [BACKEND_PATTERNS.md](BACKEND_PATTERNS.md).
+- Frontend: use [FRONTEND_CODE_FIRST.md](FRONTEND_CODE_FIRST.md), [FRONTEND_API.md](FRONTEND_API.md) e os padrões de UI indicados no catálogo.
+- Segurança: declare permissões em `central.app.json`, aplique `requirePermission` no backend e use guards públicos no frontend.
+- Capabilities: abra o contrato dedicado antes de declarar ou consumir.
+- Runtime local: preserve o comportamento fail-closed descrito em [LOCAL_SECURITY_BOUNDARY.md](LOCAL_SECURITY_BOUNDARY.md).
+
+Crie apenas código de negócio. URLs internas, credenciais, registries, transports e detalhes de implementação não pertencem ao App.
+
+## 5. Validar
+
+```bash
+npm run ooncore:docs:check
+npm run ooncore:conformance
+npm run check
+npm test
+```
+
+Além dos gates, prove o fluxo de usuário da tarefa. Para respostas binárias, valide tipo, assinatura e download; para mutações, valide permissão, tenant, idempotência e erros.
+
+## Critério final do Agent
+
+O relato de entrega deve informar:
+
+- contratos públicos consultados;
+- manifestos e pontos de extensão alterados;
+- testes e gates executados;
+- limitações do runtime local;
+- qualquer lacuna documental encontrada.
+
+Citar fonte privada como requisito de implementação significa que a tarefa ainda não atende a este contrato.

package/docs/PDF_RENDERING.md

@@ -0,0 +1,157 @@
+# Renderização de PDF
+
+Use esta capability para transformar HTML em um `Buffer` PDF sem conhecer endpoint, credencial ou implementação do serviço. Requer OonCore `0.6.0` ou superior.
+
+## Declaração
+
+Declare a dependência de infraestrutura em `oon.deploy.json`:
+
+```json
+{
+  "capabilities": {
+    "pdfRendering": {
+      "required": true,
+      "minVersion": "1.0.0"
+    }
+  }
+}
+```
+
+Não adicione URL, usuário, senha ou implementation reference. O runtime resolve esses valores na publicação. Esta declaração não pertence ao array `capabilities` de `central.app.json`.
+
+## API pública do backend
+
+```js
+const {
+  capabilities,
+  defineRoutes,
+  GenericError,
+  requirePermission,
+} = require("@oondemand/oon-core-back");
+
+defineRoutes("/pdf", (router) => {
+  router.private.post(
+    "/render",
+    requirePermission("pdf.render"),
+    async (req, res) => {
+      if (typeof req.body?.html !== "string" || !req.body.html.trim()) {
+        throw new GenericError("Informe o HTML.", {
+          statusCode: 422,
+          code: "PDF_HTML_REQUIRED",
+        });
+      }
+
+      const controller = new AbortController();
+      const abort = () => controller.abort();
+      req.once("aborted", abort);
+      res.once("close", abort);
+
+      try {
+        const pdf = await capabilities.pdf.render(
+          {
+            html: req.body.html,
+            format: req.body.format || "A4",
+            printBackground: true,
+          },
+          {
+            ...req.accessContext,
+            correlationId: req.id,
+            environment: process.env.APP_ENVIRONMENT,
+            signal: controller.signal,
+          },
+        );
+
+        res.type("application/pdf");
+        res.set("Content-Disposition", 'attachment; filename="documento.pdf"');
+        res.send(pdf);
+      } finally {
+        req.off("aborted", abort);
+        res.off("close", abort);
+      }
+    },
+  );
+});
+```
+
+Declare `pdf.render` em `rbac.permissions` e conceda-a somente aos papéis necessários. O backend continua sendo a autoridade de permissão e tenant.
+
+A assinatura é:
+
+```ts
+capabilities.pdf.render(input, context): Promise<Buffer>
+```
+
+| Campo de `input` | Tipo | Regra/default |
+|---|---|---|
+| `html` | string | obrigatório; máximo padrão de 2 MiB |
+| `format` | `A3 \| A4 \| A5 \| Letter \| Legal` | `A4` |
+| `landscape` | boolean | `false` |
+| `marginTop`, `marginBottom`, `marginLeft`, `marginRight` | number | polegadas, de 0 a 4; `0.39` |
+| `printBackground` | boolean | `true` |
+| `timeoutMs` | number | mínimo 1.000 ms; padrão 30.000 ms; máximo do runtime, padrão 60.000 ms |
+
+O `context` pode carregar `tenantId`, `appCode`, `environment`, `operationId`, `correlationId`/`requestId`, `signal` e, somente em testes, `fetchImpl`. A saída deve começar com `%PDF-` e tem limite padrão de 20 MiB.
+
+## Preview e download no frontend
+
+Preview do HTML deve usar iframe sem privilégios:
+
+```tsx
+<iframe title="Prévia" sandbox="" srcDoc={html} />
+```
+
+Para gerar e baixar usando o cliente autenticado do Core:
+
+```tsx
+import { useOonApi } from "@oondemand/oon-core-front";
+
+function DownloadPdfButton({ html }: { html: string }) {
+  const { http } = useOonApi();
+
+  async function download() {
+    const response = await http.post(
+      "/pdf/render",
+      { html, format: "A4" },
+      { responseType: "blob" },
+    );
+    const url = URL.createObjectURL(response.data);
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = "documento.pdf";
+    link.click();
+    URL.revokeObjectURL(url);
+  }
+
+  return <button onClick={download}>Gerar PDF</button>;
+}
+```
+
+Nunca envie a geração diretamente a um endpoint de infraestrutura pelo navegador.
+
+## Erros
+
+`PdfRenderingError` expõe `code`, `statusCode`, `retryable` e detalhes sanitizados.
+
+| Código | Retry | Significado |
+|---|---:|---|
+| `PDF_RENDERING_INVALID_INPUT` | não | HTML vazio ou acima do limite |
+| `PDF_RENDERING_INVALID_OPTIONS` | não | formato, margem ou opção inválida |
+| `PDF_RENDERING_UNAVAILABLE` | sim | capability não resolvida no ambiente |
+| `PDF_RENDERING_CREDENTIAL_UNAVAILABLE` | sim | credencial interna não injetada |
+| `PDF_RENDERING_IMPLEMENTATION_ERROR` | sim | implementação respondeu com falha |
+| `PDF_RENDERING_TIMEOUT` | sim | prazo excedido ou sinal abortado |
+| `PDF_RENDERING_SATURATED` | sim | concorrência/fila excedida |
+| `PDF_RENDERING_TRANSPORT_ERROR` | sim | falha transitória de transporte |
+| `PDF_RENDERING_INVALID_OUTPUT` | sim | saída inválida ou acima do limite |
+
+Use retentativas apenas quando `error.retryable === true`, com backoff e idempotência na operação chamadora.
+
+## Segurança e runtime local
+
+- trate HTML do usuário como não confiável; sanitize no App e use interpolação escapada;
+- prefira HTML autocontido; recursos remotos tornam o resultado não determinístico e podem ser bloqueados;
+- nunca inclua segredos, tokens ou credenciais no HTML;
+- não registre HTML nem bytes do PDF; registre correlação, duração, tamanhos e código de erro;
+- propague cancelamento do request por `AbortSignal`;
+- no runtime local, a capability falha fechado com `PDF_RENDERING_UNAVAILABLE` quando não resolvida;
+- em testes automatizados, um transport fake pode ser injetado por `capabilities.configurePdfRendering` e deve devolver bytes iniciados por `%PDF-`; não gere um “PDF” textual falso no código do App.

package/docs/TRANSACTIONAL_EMAIL.md

@@ -0,0 +1,111 @@
+# E-mail transacional
+
+A capability `core.transactional-email` fornece configuração protegida, templates versionados, preview, envio idempotente, fila, retentativas e painel administrativo. Requer OonCore `0.6.0` ou superior.
+
+## Declaração funcional
+
+Em `central.app.json`:
+
+```json
+{
+  "capabilities": ["core.transactional-email"],
+  "capabilitySettings": {
+    "core.transactional-email": {
+      "enabled": true,
+      "scopePolicy": "tenant_override",
+      "retentionDays": 30,
+      "attachmentsPolicy": { "allowed": false },
+      "templates": [
+        {
+          "code": "confirmacao",
+          "definition": "./emails/confirmacao.json",
+          "initialStatus": "active"
+        }
+      ]
+    }
+  }
+}
+```
+
+`scopePolicy` aceita `app_only`, `tenant_required` ou `tenant_override`. `retentionDays` aceita 1 a 90. Nesta linha do Core, anexos não são permitidos.
+
+A definição referenciada contém:
+
+```json
+{
+  "code": "confirmacao",
+  "name": "Confirmação",
+  "subject": "Olá, {{nome}}",
+  "htmlContent": "<p>Olá, {{nome}}.</p>",
+  "textContent": "Olá, {{nome}}.",
+  "variablesSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["nome"],
+    "properties": { "nome": { "type": "string" } }
+  },
+  "locale": "pt-BR",
+  "initialStatus": "active",
+  "attachmentsPolicy": { "allowed": false }
+}
+```
+
+Templates usam somente interpolação Handlebars escapada. Blocos, helpers, subexpressões, triple-stache e conteúdo remoto executável não são aceitos.
+
+## Envio no backend
+
+```js
+const { capabilities } = require("@oondemand/oon-core-back");
+
+async function enviarConfirmacao({ email, nome, idempotencyKey }, req) {
+  return capabilities.transactionalEmail.send(
+    {
+      templateCode: "confirmacao",
+      to: email,
+      variables: { nome },
+      idempotencyKey,
+      correlationId: req.id,
+      maxAttempts: 5,
+    },
+    {
+      ...req.accessContext,
+      userId: req.accessContext?.userId,
+    },
+  );
+}
+```
+
+`idempotencyKey` é obrigatória. O retorno é `{ dispatchId, status, correlationId }`; `status` é `accepted` ou `duplicate`. Não trate `accepted` como entrega confirmada.
+
+Outras operações públicas do namespace `capabilities.transactionalEmail` incluem preview e versionamento de templates, consulta de dispatches e retry de dead letter. Para administração interativa, prefira o componente do Core.
+
+## Painel administrativo
+
+```tsx
+import { CoreTransactionalEmail } from "@oondemand/oon-core-front";
+
+export function EmailPage() {
+  return <CoreTransactionalEmail />;
+}
+```
+
+Proteja a rota e declare/conceda apenas as permissões necessárias:
+
+- `transactional-email.config.read`
+- `transactional-email.config.manage`
+- `transactional-email.templates.read`
+- `transactional-email.templates.manage`
+- `transactional-email.dispatches.read`
+- `transactional-email.dispatches.retry`
+
+O componente usa as rotas autenticadas em `/core/transactional-email/*`. Credenciais são inseridas pela tela protegida e armazenadas pelo Core; nunca as coloque no manifesto, frontend, repositório ou log.
+
+## Segurança e operação
+
+- o backend resolve app e tenant a partir do contexto validado;
+- `tenant_required` exige tenant; `tenant_override` usa configuração do tenant quando houver e recua para a do App;
+- destinatários e variáveis são validados antes de enfileirar;
+- payload protegido tem retenção limitada; listagens não retornam o payload protegido;
+- erros usam `TransactionalEmailError` e códigos `EMAIL_*` sanitizados;
+- no runtime local, falhe fechado até a capability e seu secret store/configuração estarem disponíveis;
+- testes devem substituir a fronteira externa; não envie e-mail real e não grave credenciais de teste.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oondemand/create-central-oon",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oondemand/oon-platform.git",

package/schemas/central.app.schema.json

@@ -220,6 +220,70 @@
           }
         }
       }
+    },
+    "capabilitySettings": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "core.transactional-email": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "enabled",
+            "scopePolicy",
+            "templates"
+          ],
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "scopePolicy": {
+              "enum": [
+                "app_only",
+                "tenant_required",
+                "tenant_override"
+              ]
+            },
+            "retentionDays": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 90
+            },
+            "attachmentsPolicy": {
+              "type": "object"
+            },
+            "templates": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "code",
+                  "definition",
+                  "initialStatus"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+                  },
+                  "definition": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "^(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+$"
+                  },
+                  "initialStatus": {
+                    "enum": [
+                      "draft",
+                      "active"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "allOf": [

package/src/index.js

@@ -91,9 +91,20 @@ function copiedDocsHash(docsDir, files) {
   return hash.digest("hex");
 }
 
+function rootAgentEntrypoint() {
+  return [
+    "# OonCore — entrada para IA/Agents",
+    "",
+    "Leia o contrato canônico completo em [docs/AGENTS.md](docs/AGENTS.md).",
+    "",
+    "Confira \`.ooncore/manifest.json\` e execute \`npm run ooncore:docs:check\` antes de alterar o App.",
+    "",
+  ].join("\n");
+}
+
 function entrypointContents(files = listDocFiles()) {
   return {
-    "AGENTS.md": fs.readFileSync(path.join(DOCS_DIR, "AGENTS.md"), "utf8"),
+    "AGENTS.md": rootAgentEntrypoint(),
     "CODEX.md": fs.readFileSync(path.join(DOCS_DIR, "CODEX.md"), "utf8"),
     "context.generated.md": buildContext(files),
   };
@@ -219,10 +230,9 @@ function syncDocs(opts = {}) {
   removeDir(docsOutDir);
   copyDocs(DOCS_DIR, docsOutDir);
 
-  for (const entrypoint of ["AGENTS.md", "CODEX.md"]) {
-    const source = path.join(DOCS_DIR, entrypoint);
-    if (fs.existsSync(source)) fs.copyFileSync(source, path.join(outDir, entrypoint));
-  }
+  fs.writeFileSync(path.join(outDir, "AGENTS.md"), rootAgentEntrypoint());
+  const codexSource = path.join(DOCS_DIR, "CODEX.md");
+  if (fs.existsSync(codexSource)) fs.copyFileSync(codexSource, path.join(outDir, "CODEX.md"));
 
   fs.writeFileSync(path.join(outDir, "context.generated.md"), buildContext(files));
   fs.writeFileSync(path.join(outDir, "manifest.json"), `${JSON.stringify(buildManifest(files), null, 2)}\n`);

package/templates/_base/README.md

@@ -2,14 +2,27 @@
 
 App Oon code-first gerado com `create-central-oon`.
 
+## Comece aqui
+
+A pasta `.ooncore/` contém o contrato público versionado para criar e customizar este App. Um Agent deve usar somente esta árvore do projeto: não é necessário consultar fonte privada do OonCore, `node_modules` ou outros Apps.
+
+1. Leia `.ooncore/AGENTS.md`.
+2. Rode `npm run ooncore:docs:check`.
+3. Siga `.ooncore/docs/OON_APP_AGENT_GUIDE.md`.
+4. Consulte `.ooncore/docs/CAPABILITIES.md` e o guia específico da tarefa.
+
+Se faltar um contrato, registre a lacuna documental em vez de inventar API ou infraestrutura.
+
 ## Fronteira arquitetural
 
-- `central.app.json` declara identidade, `appKind`, módulos, capabilities e compatibilidade com o OonCore;
-- `backend/central.domain.json` declara models e regras do domínio;
+- `central.app.json` declara identidade, `appKind`, tenant, acesso, módulos, capabilities funcionais e compatibilidade;
+- `oon.deploy.json` declara runtime e dependências de infraestrutura da publicação;
+- `backend/src/models` e demais extensões code-first contêm o domínio;
+- `backend/central.domain.json` é opcional quando o projeto adota o contrato declarativo documentado;
 - `frontend/src/app` compõe rotas, navegação, layouts e temas;
 - `frontend/src/{pages,components,features}` contém a experiência local;
-- `backend/central.config.js` fica reservado a extensões excepcionais de runtime;
-- `frontend/src/main.tsx` chama o bootstrap code-first `startOonApp`.
+- `backend/central.config.js` fica reservado a extensões documentadas de runtime;
+- `frontend/src/main.tsx` chama `startOonApp`.
 
 Autenticação, guards, shell, RBAC, metadata, CRUD e infraestrutura pertencem ao OonCore.
 
@@ -20,9 +33,10 @@ npm run ooncore:docs        # sincroniza .ooncore/
 npm run ooncore:docs:check  # valida versão/hash do cache local
 npm run ooncore:conformance # valida a fronteira da Central
 npm run check               # executa os gates locais
+npm test
 ```
 
-A pasta `.ooncore/` é um cache regenerável da documentação publicada no pacote. Não edite `context.generated.md` manualmente.
+`.ooncore/` é um cache regenerável da documentação publicada no pacote. Não edite `context.generated.md` manualmente; versione a pasta junto com o App para que humanos e Agents recebam o mesmo contrato.
 
 ## Rodando
 
@@ -35,13 +49,14 @@ cp frontend/.env.example frontend/.env
 npm run dev
 ```
 
-O comando inicia backend e frontend exclusivamente em loopback, abre uma sessão local aleatória e não consulta nem cria recursos na plataforma. Não implemente autenticação ou ativação paralela na Central.
+O comando inicia backend e frontend exclusivamente em loopback, abre uma sessão local aleatória e não consulta nem cria recursos na plataforma. Capabilities de plataforma falham fechado quando não resolvidas. Não implemente autenticação, ativação ou infraestrutura paralela.
 
 ## Evoluindo a Central
 
-1. Declare domínio e fórmulas em `backend/central.domain.json`.
-2. Crie rotas, páginas, componentes, layouts e temas no frontend.
-3. Use validações, triggers, hooks, mappings e regras somente para comportamento específico do negócio.
-4. Execute `npm run check` antes de abrir o PR.
+1. Modele o domínio por exports públicos em `backend/src` ou adote o manifesto declarativo conforme `BACKEND_DOMAIN_MANIFEST.md`.
+2. Crie rotas, páginas, componentes, layouts e temas nos pontos documentados.
+3. Declare capabilities no manifesto indicado pelo guia dedicado.
+4. Use validações, triggers, hooks, mappings e regras somente para comportamento específico do negócio.
+5. Execute `npm run check` e `npm test` antes de abrir o PR.
 
 O OonCore fornece a fundação; o App implementa sua experiência e seu domínio.

package/templates/_base/backend/package.json

@@ -12,6 +12,6 @@
     "deploy": "oonCore-back deploy"
   },
   "dependencies": {
-    "@oondemand/oon-core-back": "^0.6.2"
+    "@oondemand/oon-core-back": "^0.6.4"
   }
 }

package/templates/_base/frontend/package.json

@@ -11,7 +11,7 @@
     "sync:metadata": "oonCore-front sync:metadata"
   },
   "dependencies": {
-    "@oondemand/oon-core-front": "^0.6.2",
+    "@oondemand/oon-core-front": "^0.6.4",
     "@chakra-ui/react": "^3.13.0",
     "@emotion/react": "^11.14.0",
     "@tanstack/react-query": "^5.65.0",

package/templates/_base/package.json

@@ -13,6 +13,6 @@
     "dev:frontend": "npm run dev --prefix frontend"
   },
   "devDependencies": {
-    "@oondemand/create-central-oon": "0.6.2"
+    "@oondemand/create-central-oon": "0.6.4"
   }
 }