@oondemand/create-central-oon 0.7.3 → 0.7.6

package/README.md

@@ -2,13 +2,24 @@
 
 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
+## Comece com uma jornada
+
+Resolva uma release publicada uma vez e gere a base oficial (Bash):
 
 ```bash
-npx --yes --package @oondemand/create-central-oon@0.6 create-central-oon central-exemplo
+OONCORE_VERSION="$(npm view @oondemand/create-central-oon version)"
+npx --yes --package "@oondemand/create-central-oon@$OONCORE_VERSION" create-central-oon meu-app --no-install
+cd meu-app
+npm install
+npm install --prefix backend
+npm install --prefix frontend
 ```
 
-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 guia gerado em `.ooncore/docs/OON_APP_AGENT_GUIDE.md` contém o comando com a versão exata do pacote instalado: gerar → executar → implementar primeira jornada → validar → publicar pelo fluxo existente. Consulte `.ooncore/docs/TASK_INDEX.md` somente para a tarefa necessária.
+
+O gerador possui uma única base `_base`; não há catálogo de templates funcionais. Após gerar uma base limpa, `npx --no-install create-central-oon example` instala a jornada opt-in documentada em `.ooncore/docs/EXECUTABLE_EXAMPLE.md`. O binário também responde por `scaffold-central-oon`. Os tokens `__OONCORE_*__` nas fontes documentais são resolvidos pelo sync oficial a partir do `package.json`, inclusive nos hashes do cache.
+
+As seções abaixo são referências sob demanda, não pré-requisitos para começar.
 
 ## Contrato `central.app.json`
 
@@ -74,22 +85,15 @@ Um domínio declarativo pode adicionar `backend/central.domain.json` conforme se
 
 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.
 
-Comece por:
-
-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.
-
-Se faltar informação pública, registre a lacuna; não deduza APIs por implementação interna.
+Comece pela entrada curta `.ooncore/AGENTS.md` e pelo índice por intenção. Se faltar informação pública, registre a lacuna, use extensão pública adequada no App e continue partes independentes. Não invente APIs nem use internals como contrato. O contexto consolidado é opcional.
 
 ## Conformidade
 
 ```bash
-npm run ooncore:docs:check
-npm run ooncore:conformance
 npm run check
-npm test
+npm run build --prefix frontend
 ```
 
 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.
+
+Execute também os testes relevantes declarados pelo App. O scaffold não cria `npm test` na raiz. Plataforma homologada: consuma os fluxos existentes; não reabra sua implementação ou homologação global a cada jornada.

package/bin/cli.js

@@ -31,7 +31,7 @@ function parseArgs(argv) {
     else throw new Error(`Opção desconhecida: ${arg}.`);
   }
 
-  if (["docs", "conformance", "dev"].includes(positionals[0])) {
+  if (["docs", "conformance", "dev", "doctor", "example"].includes(positionals[0])) {
     opts.command = positionals[0];
     if (opts.command === "docs" && positionals[1] === "check") opts.docsCheck = true;
     if (opts.command === "docs" && positionals[1] === "sync") opts.docsSync = true;
@@ -44,12 +44,22 @@ function printUsage() {
   console.error("  npx create-central-oon <nome-do-app>");
   console.error("  npx create-central-oon docs sync|check");
   console.error("  npx create-central-oon conformance [--root .] [--json]");
-  console.error("  npx create-central-oon dev");
+  console.error("  npx create-central-oon dev|doctor|example [--root .]");
 }
 
 async function main() {
   try {
     const opts = parseArgs(process.argv.slice(2));
+    if (opts.command === "example") {
+      require("../src/example").installExample({ cwd: opts.root || process.cwd() });
+      return;
+    }
+    if (opts.command === "doctor") {
+      const result = require("../src/doctor").doctor({ cwd: opts.root || process.cwd() });
+      console.log(JSON.stringify(result, null, 2));
+      process.exitCode = result.ok ? 0 : 1;
+      return;
+    }
     if (opts.command === "docs") {
       if (opts.docsCheck) checkDocs();
       else syncDocs();

package/docs/AGENTS.md

@@ -1,58 +1,14 @@
 # OonCore — entrada canônica para IA/Agents
 
-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. 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.
-
-## Roteamento por tarefa
-
-| Tarefa | Leitura obrigatória |
-|---|---|
-| 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) |
-| Publicação, imports e assets de runtime | [APP_PACKAGING.md](APP_PACKAGING.md) |
-| Upgrade do Core | [CORE_UPGRADE.md](CORE_UPGRADE.md), [TESTING_CONFORMANCE.md](TESTING_CONFORMANCE.md), [releases/0.7.0.md](releases/0.7.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
-
-- O App declara domínio e experiência em código; o Core fornece bootstrap, autenticação, ativação, RBAC, tenant, CRUD, metadata, shell, componentes genéricos e deployment.
-- Use somente exports públicos documentados. Arquivos internos de `src/` não são contrato de extensão.
-- Autorização, tenant e regras que alteram dados são sempre validados no backend.
-- Não crie autenticação, ativação, RBAC, CRUD, shell, registry ou infraestrutura paralelos.
-- Não coloque segredos em manifesto, frontend, log, URL permanente ou documentação.
-- Recursos de plataforma devem falhar fechado no runtime local.
-
-## Gates antes de concluir
-
-```bash
-npm run ooncore:docs:check
-npm run ooncore:conformance
-npm run check
-npm test
-```
-
-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.
-
+Leia o `AGENTS.md` da raiz do App, quando existir, e siga o roteiro curto em [OON_APP_AGENT_GUIDE.md](OON_APP_AGENT_GUIDE.md). Para uma alteração existente, vá direto à intenção em [TASK_INDEX.md](TASK_INDEX.md).
+
+- Use a documentação distribuída correspondente aos pacotes instalados. `npm run check` verifica cache e conformidade; se o cache estiver desatualizado, regenere com `npm run ooncore:docs`.
+- Leia somente a referência necessária à jornada. `context.generated.md` é uma compilação opcional para consulta, não uma leitura inicial obrigatória.
+- Use exports públicos; fontes internas e outros Apps não substituem contratos. Exemplos de domínio de outros Apps não são scaffold.
+- Se faltar contrato, registre a lacuna com versão, tarefa e informação ausente. Use uma extensão pública documentada no próprio App quando adequada e continue as partes independentes. Suspenda apenas a operação que não pode ser implementada com segurança; não invente APIs nem importe internals.
+- 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 existentes. Não repita sua implementação/homologação global no App. Nova Capacidade exige escopo separado e explícito.
+- Entregue uma jornada utilizável com página, navegação, endpoint e permissão. Admin pode validar a POC controlada; uma matriz final de perfis, roadmap completo e novas Capacidades não são pré-requisitos.
+- Antes do PR: `npm run check`, build do frontend e testes relevantes existentes. Relate separadamente implementação, build, publicação e homologação da jornada.
+
+O `AGENTS.md` da raiz pertence ao App; o gerador e o sync não o sobrescrevem. Consulte [CORE_UPGRADE.md](CORE_UPGRADE.md) para migração e [releases/0.7.0.md](releases/0.7.0.md) para o histórico desta linha.

package/docs/AGENT_WORKFLOW.md

@@ -1,20 +1,13 @@
 # Fluxo de trabalho para Agents
 
-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.
+1. Gere a base oficial e execute: [OON_APP_AGENT_GUIDE.md](OON_APP_AGENT_GUIDE.md).
+2. Escolha a jornada e consulte somente a intenção em [TASK_INDEX.md](TASK_INDEX.md).
+3. Implemente domínio e experiência pelos contratos públicos, preservando permissões, contexto e segredos.
+4. Valide com `npm run check`, build e testes relevantes disponíveis; prove a jornada.
+5. Publique pelo fluxo existente e registre commit e evidência em Dev.
 
-## Regra closed-book
+A documentação desta release é __OONCORE_VERSION__, linha __OONCORE_LINE__.x. Para coordenar os três pacotes, consulte [CORE_UPGRADE.md](CORE_UPGRADE.md).
 
-Mantenha os três pacotes OonCore na linha 0.7.x declarada pelo App e sincronize `.ooncore` após qualquer atualização.
+Se faltar assinatura, declaração, exemplo ou limite, registre a lacuna e continue partes independentes com extensões públicas documentadas no App. Apenas a operação sem contrato seguro fica pendente. Nunca use internals como API, invente contratos ou crie autoridade de autenticação/RBAC paralela.
 
-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:
-
-> 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.
+Não exija leitura integral do contexto consolidado, planejamento completo nem homologação global da Plataforma para começar. Consulte referências detalhadas sob demanda.

package/docs/BACKEND_API.md

@@ -4,8 +4,8 @@ Importe exclusivamente de `@oondemand/oon-core-back`. Caminhos internos não tê
 
 ## Boot e definição
 
-- `start(options)`: carrega a Central, conecta Mongo, inicializa capabilities e inicia HTTP. `options.listen=false` devolve somente o app.
-- `createApp()`: cria o Express já protegido e com rotas do Core.
+- `start({ cwd, listen })`: carrega o backend indicado por `cwd`, conecta Mongo, inicializa capabilities e inicia HTTP. `listen=false` devolve `{ app }`; com escuta, `{ app, server }`.
+- `createApp()`: monta o Express já protegido usando o registro existente; não carrega os módulos do App nem conecta o banco sozinho.
 - `activate()`: fluxo legado de ativação; não é usado no runtime local.
 - `defineCentral`, `defineModel`, `defineCollection`, `defineDocument`, `definePipeline`, `defineRoutes`, `defineValidation`, `defineTrigger`: extensões imperativas suportadas.
 - `fields`: factories de campos compatíveis com schema e metadata.
@@ -13,10 +13,10 @@ Importe exclusivamente de `@oondemand/oon-core-back`. Caminhos internos não tê
 
 ## Segurança, RBAC e tenant
 
-- `requirePermission(permission)`: middleware obrigatório em rotas sensíveis.
+- `requirePermission(permission)`: middleware público de autorização. Em `router.private`, declare `{ permission }` no segundo argumento; não passe middleware nessa posição. Veja [PUBLIC_CONTRACTS.md](PUBLIC_CONTRACTS.md).
 - `CORE_PERMISSIONS`, `rbacPolicy`, `roleByCode`, `permissionGranted`: leitura e avaliação da política declarada.
 - `TENANT_HEADER`, `TENANCY_MODELS`, `DATA_SCOPES`: constantes canônicas.
-- `createAccessContext`, `readRequestedTenantId`: produzem contexto validado.
+- `createAccessContext` estrutura identidade já verificada; `readRequestedTenantId` lê a seleção solicitada, sem autenticá-la. Nas rotas use `req.accessContext`.
 - `scopeFilter`, `mergeScopedFilter`, `scopeMutation`, `scopedIdFilter`: aplicam isolamento aos dados. Nunca aceite tenant do body como autoridade.
 
 ## Manifestos
@@ -46,4 +46,4 @@ O namespace público `localDevelopment` expõe detecção, validação de loopba
 
 ## Erros
 
-`GenericError(message, { statusCode, code, details })` é o erro operacional base. Rotas devem lançá-lo e deixar o middleware do Core produzir o envelope sanitizado.
+`GenericError(message, { statusCode, code, details })` é o erro operacional base. O App deve fornecer mensagem/detalhes seguros; o middleware produz o envelope, mas não remove automaticamente segredos do conteúdo arbitrário fornecido pelo App. Bootstrap, rotas, prefixos, permissões e `sensitiveBody` estão consolidados em [PUBLIC_CONTRACTS.md](PUBLIC_CONTRACTS.md).

package/docs/BACKEND_DOMAIN_MANIFEST.md

@@ -229,7 +229,7 @@ Não declare a mesma model no manifesto e em `src/models`. O registry interrompe
 Campos calculados:
 
 - são automaticamente `readonly`;
-- recebem `immutable` no schema Mongoose;
+- são protegidos pelo pipeline de mutação HTTP; valores calculados continuam graváveis pelo próprio Core após recálculo;
 - são recalculados no backend em criação, edição, patch e importação;
 - são calculados em ordem de dependência;
 - não podem formar ciclos;

package/docs/CAPABILITIES.md

@@ -1,6 +1,6 @@
 # Catálogo de capacidades do OonCore
 
-Consulte este catálogo antes de criar infraestrutura ou componentes customizados. Para capabilities nativas, o guia dedicado é leitura obrigatória.
+Comece pela tarefa em [TASK_INDEX.md](TASK_INDEX.md), com API pública, piso de versão, exemplo e limite. Este catálogo é referência adicional sob demanda; consulte somente os guias das capabilities usadas.
 
 | Capacidade | Backend | Frontend | Declaração/extensão | Local | Plataforma |
 |---|---|---|---|---|---|
@@ -14,10 +14,18 @@ Consulte este catálogo antes de criar infraestrutura ou componentes customizado
 | 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 |
+| Recálculos de processo | manifesto de processo; execução específica | projeção do estado | `central.process.json` | Sim | Sim |
 | E-mail transacional | `capabilities.transactionalEmail` | `CoreTransactionalEmail` | [TRANSACTIONAL_EMAIL.md](TRANSACTIONAL_EMAIL.md) | Fail-closed/dublê de teste | Implementação resolvida pelo Core |
+| Segredos V1 | `capabilities.secrets` | Formulário do App | [SECRETS.md](SECRETS.md) | Chave local explícita | Chave por runtime dedicado/ambiente |
 | 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 |
+| Publicação/promoção | serviço homologado da Plataforma | Workspace existente | consumir fluxo existente; não reimplementar | 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 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.
+
+
+Não há contrato público genérico de integration runtime. Workers de e-mail e jobs de recálculo são específicos; execução durável genérica e diagnóstico de integrações são propostas separadas. Consulte [ROUTES_HOOKS_WORKERS.md](ROUTES_HOOKS_WORKERS.md).
+
+## Aplicação dos recursos nativos
+
+A página `/recursos` do exemplo demonstra fórmulas, validações, bindings, invariantes, documentos, dashboard e PDF. O serviço de e-mail é opt-in. Consulte [NATIVE_RESOURCES.md](NATIVE_RESOURCES.md) para o roteiro, helpers de escopo e limites reais de isolamento, auditoria e execução.

package/docs/CHECKLIST_IMPLEMENTACAO.md

@@ -1,6 +1,6 @@
 # Checklist de Implementação
 
-Use este checklist antes de concluir qualquer tarefa de codificação em uma Central Oon.
+Referência sob demanda: aplique somente os itens relevantes à jornada alterada. Não é um gate para começar uma POC nem exige homologar novamente a Plataforma.
 
 ## Contexto e documentação
 
@@ -34,7 +34,7 @@ Use este checklist antes de concluir qualquer tarefa de codificação em uma Cen
 ## Integrações e capabilities
 
 - [ ] Fiz a declaração no manifesto indicado pelo guia.
-- [ ] Usei camada de integração/capability pública.
+- [ ] Usei serviço do App ou capability com contrato público publicado; não assumi uma fila genérica do Core.
 - [ ] 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.
@@ -42,9 +42,8 @@ Use este checklist antes de concluir qualquer tarefa de codificação em uma Cen
 
 ## Entrega
 
-- [ ] `npm run ooncore:docs:check` passou.
-- [ ] `npm run ooncore:conformance` passou.
-- [ ] `npm run check` e `npm test` passaram.
+- [ ] `npm run check` passou (inclui docs check e conformance).
+- [ ] Build e testes relevantes declarados pelo App 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.

package/docs/CORE_UPGRADE.md

@@ -1,20 +1,23 @@
 # Atualização coordenada do OonCore
 
-Os três pacotes devem permanecer na mesma linha:
+Esta documentação corresponde à release **__OONCORE_VERSION__**, linha `__OONCORE_LINE__.x`. Preserve as regras e o domínio do App. Escolha uma versão publicada e compatível e atualize backend, frontend e gerador juntos.
 
-- `@oondemand/oon-core-back`;
-- `@oondemand/oon-core-front`;
-- `@oondemand/create-central-oon`.
+Na raiz do App, para adotar a release deste guia:
 
-## Procedimento para Agent
+```bash
+npm install --save-dev --save-exact @oondemand/create-central-oon@__OONCORE_VERSION__
+npm install --prefix backend --save-exact @oondemand/oon-core-back@__OONCORE_VERSION__
+npm install --prefix frontend --save-exact @oondemand/oon-core-front@__OONCORE_VERSION__
+npm run ooncore:docs
+npx --no-install create-central-oon doctor
+npm run build --prefix frontend
+```
 
-1. Leia o `AGENTS.md` da raiz e preserve regras/domínio do projeto.
-2. Registre versões atuais, lockfiles e `central.app.json`.
-3. Atualize os três pacotes para a mesma versão `0.7.x`.
-4. Ajuste compatibilidade para `>=0.7.0 <0.8.0` somente quando a migração estiver pronta.
-5. Rode `npm run ooncore:docs` e revise o diff de `.ooncore/`.
-6. Remova `DEV_TOKEN`, `VITE_DEV_TOKEN`, tokens fixos e URLs da plataforma do caminho local.
-7. Preserve `AGENTS.md` raiz, models, regras, provas e documentação do domínio.
-8. Execute docs check, conformance, typecheck, testes e smoke offline.
+O comando oficial regenera cache, manifesto e hashes; nunca edite `.ooncore` à mão. Versione os três package.json, seus lockfiles e o cache. Em Apps organizados como workspaces, use as opções de workspace equivalentes e preserve o lockfile único do projeto.
 
-Não atualize somente um pacote e não copie arquivos do Core manualmente para a Central.
+Revise `central.app.json#compatibility.core` conforme as funções usadas e só aumente o mínimo após validar a migração. A faixa da linha é `__OONCORE_RANGE__`; os exemplos de [TASK_INDEX.md](TASK_INDEX.md) indicam seu piso específico. Não confunda o schema do manifesto com a versão do pacote.
+
+Execute os testes existentes e o smoke da jornada. Testes do App devem verificar comportamento/compatibilidade, não um literal de versão antiga sem justificativa. Preserve configurações operacionais de publicação; tokens fixos e identidade de plataforma não pertencem ao caminho local. Publique pelo fluxo existente e registre o commit homologado em Dev. Nenhum outro App precisa atualizar por causa desta entrega.
+
+
+Em Apps existentes, altere o script raiz `check` para `create-central-oon doctor`. Ele já inclui cache e conformance: não duplique essas duas verificações no mesmo CI. O procedimento acima preserva o domínio; o comando `example` é somente para bases novas. Falha parcial em npm install exige concluir os três upgrades antes do sync/check; não publique versões divergentes.

package/docs/ERRORS.md

@@ -1,6 +1,6 @@
 # Contrato de erros
 
-Erros operacionais usam `{ error: { code, message, details?, requestId? } }` e status HTTP coerente.
+Erros de domínio lançados com `GenericError` e `code` usam `{ message, error: { code, message, details?, requestId? } }` e status HTTP coerente. O App fornece mensagem/detalhes seguros; não há sanitização genérica de qualquer objeto externo. Respostas legadas/auth podem ter somente `message` e um 404 de proxy/Express pode ser HTML. Veja [PUBLIC_CONTRACTS.md](PUBLIC_CONTRACTS.md).
 
 | Código | Significado |
 |---|---|

package/docs/EXECUTABLE_EXAMPLE.md

@@ -0,0 +1,42 @@
+# Exemplo integrado e diagnóstico de autoria
+
+Disponível na release __OONCORE_VERSION__. Gere a base oficial seguindo [a entrada curta](OON_APP_AGENT_GUIDE.md). Na raiz da base limpa, com gerador instalado:
+
+```bash
+npx --no-install create-central-oon example
+npm run dev
+```
+
+O comando instala model/CRUD/lista de Pessoas, formulário com rota privada, Tickets com transição de processo e consulta externa HTTPS. Inclui página `/jornada`, item **Primeira jornada** no menu e permissões no manifesto. `FIRST_JOURNEY.md` acompanha os arquivos e explica a execução. O comando verifica colisões e composição original antes de escrever; não sobrescreve trabalho existente. A base neutra continua sendo o padrão e o exemplo é opcional.
+
+Use admin para validar a jornada; viewer comprova 403 sem reconfigurar a Plataforma. O segredo de integração fica exclusivamente na variável backend `INTEGRACAO_TOKEN`; `INTEGRACAO_URL` deve ser um destino HTTPS controlado pelo operador, sem credenciais na URL. Não envie token pela UI, não versione `.env`, não salve segredo pelo CRUD genérico. A rota `/integracao/testar` não armazena credenciais. A jornada adicional `/segredos` usa core.secrets V1 conforme [SECRETS.md](SECRETS.md), com cadastro em objeto, estado, uso e remoção. Não há fila ou retry genéricos. A página permanece visível para demonstrar a recusa e exibir diagnóstico; a proteção efetiva está nos endpoints.
+
+Pessoa usa escopo tenant explícito. Ticket declarativo é restrito a single_tenant dedicado devido ao limite atual de propagação de escopo do domain manifest. O exemplo não é contrato para compartilhar essa model entre tenants.
+
+## Uma entrada de checks
+
+```bash
+npm run check
+npm run build --prefix frontend
+```
+
+O novo scaffold usa `create-central-oon doctor` em `check`. Para um App anterior, substitua seu comando equivalente, preservando testes próprios. Doctor inclui:
+
+- mesma versão instalada de backend/frontend/gerador e correspondência entre package.json e lockfile;
+- lockfiles npm v2/v3 separados, ou lock único de workspace com backend/frontend declarados;
+- App manifest, manifestos opcionais de domínio/processo e conformidade;
+- cache oficial e hashes; corrija com `npm run ooncore:docs`;
+- módulos TS/ESM não autocarregáveis, sintaxe CommonJS e imports relativos de diretórios de autoload que escapam de backend/;
+- indicação de cwd e mapeamento `/api` público para rota interna, conforme configuração do scaffold.
+
+Saída JSON contém códigos/caminhos e retorna exit code 1 quando houver pendências. Doctor não executa código do App, não resolve imports dinâmicos, não prova configurações de proxy modificadas e não substitui HTTP autenticado nem validação da imagem. Veja [empacotamento](APP_PACKAGING.md).
+
+## Provas no SDK
+
+A suíte gera o App pela base oficial e instala esses mesmos arquivos. Com o Core real, MongoDB descartável e servidor HTTPS de teste, verifica execução do handler, validação, CRUD persistido, transição permitida/recusada, sessão/CSRF, 401/403, chamada externa e ausência do segredo em respostas/requestLog. Reinicia em outro processo com a estrutura backend/ + central.app.json, confirma persistência e testa cwd absoluto, relativo e diretório de execução backend.
+
+`npm run check:authoring` no monorepo valida o gerador e compila a UI gerada após o build frontend. A suíte backend é executada separadamente uma única vez pelo CI e contém a jornada HTTP. Essas provas não afirmam que uma release já foi publicada, que uma imagem foi homologada ou que o emissor já foi atualizado. O 404 do emissor requer sua própria prova funcional em Dev.
+
+## Aplicação dos recursos nativos
+
+A página `/recursos` do exemplo demonstra fórmulas, validações, bindings, invariantes, documentos, dashboard e PDF. O serviço de e-mail é opt-in. Consulte [NATIVE_RESOURCES.md](NATIVE_RESOURCES.md) para o roteiro, helpers de escopo e limites reais de isolamento, auditoria e execução.

package/docs/NATIVE_RESOURCES.md

@@ -0,0 +1,94 @@
+# Recursos nativos: usar por tarefa, com fronteiras claras
+
+Release **__OONCORE_VERSION__**. Esta é uma demonstração opcional, não uma migração obrigatória. Instale o exemplo em uma base limpa com `npx --no-install create-central-oon example`; abra **Primeira jornada** (`/jornada`) e **Recursos nativos** (`/recursos`). O App existente pode adotar somente a parte necessária. As fontes ficam em `examples/first-journey` do gerador instalado e são copiadas para o App; os testes do SDK executam esses mesmos arquivos com Core e MongoDB reais.
+
+## O que usar e o que continua no App
+
+| Necessidade | Recurso público demonstrado | Fronteira |
+|---|---|---|
+| Cadastro/lista/formulário | `defineModel`, `fields`, CRUD, metadata e `CoreCollection` | Regras de negócio são declaradas pelo App; não salvar segredos no CRUD genérico |
+| Regras do próprio registro | `central.domain.json`: validações e `computed` | AST fechada; backend recalcula e recusa adulteração, prévia na UI não concede autoridade |
+| Etapas e bloqueios | `central.process.json`: workflow; `CorePipeline` em `/jornada` | PATCH direto também precisa satisfazer a regra; esconder botão não protege dado |
+| Valores relacionados | bindings `lookup`, `aggregate`, `expression` | Dependências e filtros devem estar declarados; não é sincronização com Omie |
+| Limite concorrente | `relatedSumLteParentField` | Transação MongoDB exige replica set; protege mutações da model filha, não toda mudança arbitrária no pai |
+| Documentos | `CoreDocument` com model `Documento` | Cadastro de textos; não promete upload, aprovação ou assinatura. Essas operações exigem contratos próprios |
+| Indicadores | `CoreDashboard`: count, sum, groupCount | Agrega no backend; exemplo usa apenas models do banco single-tenant dedicado |
+| UX específica | Página React local, `useOonApi`, componentes públicos | Composição code-first; não substituir shell, sessão, RBAC ou guards |
+| Rota/dado autorizado | `defineRoutes`, `req.accessContext`, helpers de escopo | Contexto vem da autenticação; não de tenant/app/roles enviados livremente |
+| Rastreabilidade | Auditoria do CRUD, `audit`, requestLog e `sensitiveBody` | Nenhum desses recursos cifra automaticamente os dados de domínio |
+| PDF/e-mail | `capabilities.pdf.render`, `capabilities.transactionalEmail.send` | Capabilities existentes, declaradas/configuradas separadamente; não são fila genérica de integração |
+
+## Roteiro de domínio e processo
+
+Em **Contratos**, crie título `Exemplo`, quantidade `2`, valor unitário `50`. A metadata gera o formulário; o backend calcula `total=100`. A validação ilustrativa limita total a 1000. Enviar total adulterado pelo PATCH é recusado. A regra comercial e os valores são apenas didáticos.
+
+Em **Parcelas**, selecione esse contrato e informe 40. O lookup preenche `tituloContrato`; o agregado atualiza `pago=40`; a expressão produz `saldo=60`. Renomeie o contrato enquanto aberto: o lookup é recalculado assincronamente. Reabra/atualize a lista para ver o estado persistido; não há promessa de push em tempo real.
+
+Feche o contrato antes de continuar as parcelas. `lockedFieldsByStage` impede alterar título, quantidade e valor unitário; não é permitido voltar para Aberto. Uma parcela de 61 é recusada pela invariável. Duas requisições simultâneas de 40 disputando saldo 60 resultam em uma inclusão e uma recusa. A exclusão do contrato com parcelas também é bloqueada.
+
+**Limite do exemplo:** a invariável está na model filha. Não garante que reduzir o total de um pai aberto preserve a soma anterior. A aplicação real precisa definir sua política para alteração/reabertura do pai; fechar o contrato estabiliza as entradas neste roteiro. O exemplo não é um módulo financeiro pronto.
+
+`Contrato`, `Parcela` e `Ticket` são restritos ao App **single_tenant dedicado**: o domain manifest desta linha não propaga `scope`/`tenancy` para as models. Não adicionar campos inventados ao JSON nem adotar esses exemplos para isolamento de linhas multi-tenant. `Pessoa` e `Documento` usam `defineModel({ scope: "tenant" })` explicitamente.
+
+O dashboard desta release aplica `crud.permissions.read` (com fallback legado de roles) e os helpers de escopo a todas as agregações. Models `legacy` continuam sem filtro de linha: a declaração correta do escopo permanece necessária. O exemplo demonstra Contrato no banco dedicado e a suíte comprova que Pessoa com escopo tenant não conta nem agrupa registros de outro tenant.
+
+Referências sob demanda: [domínio](BACKEND_DOMAIN_MANIFEST.md), [fórmulas](REACTIVE_DOMAIN_FORMULAS.md), [processo](BACKEND_PROCESS_MANIFEST.md), [coleções/esteiras](COLLECTIONS_AND_PIPELINES.md).
+
+## Rotas e helpers de escopo
+
+O `defineModel` público devolve a entrada da model, com `definition` e `mongooseModel`. O exemplo exporta essa entrada de `src/models/Pessoa.js`. A rota `GET /recursos/pessoas/contagem` exige `pessoas.read` e usa:
+
+```js
+const { mergeScopedFilter } = require("@oondemand/oon-core-back");
+const pessoa = require("../models/Pessoa");
+// Dentro de um handler privado já autenticado/autorizado:
+const filter = mergeScopedFilter(pessoa, {}, req.accessContext);
+const total = await pessoa.mongooseModel.countDocuments(filter);
+```
+
+| Helper | Assinatura | Uso |
+|---|---|---|
+| `scopeFilter` | `(entryOrDefinition, accessContext)` | Filtro obrigatório de tenant/usuário |
+| `mergeScopedFilter` | `(entryOrDefinition, filter, accessContext)` | Acrescenta escopo confiável a filtros de negócio permitidos |
+| `scopedIdFilter` | `(entryOrDefinition, id, accessContext)` | Busca por ID dentro do escopo |
+| `scopeMutation` | `(entryOrDefinition, data, accessContext)` | Impõe identidade confiável ao payload |
+
+Os helpers não autenticam, não concedem permissão e não validam regras de domínio. Para `scope: "tenant"`, contexto sem tenant é recusado; `legacy`/`system` não produzem filtro de isolamento. Nunca repasse `req.query`/operadores Mongo arbitrários. `createAccessContext` estrutura uma identidade **já verificada**: não verifica um token nem autentica um body. Prefira `req.accessContext` nas rotas do App. Mutação direta pelo Mongoose não substitui o pipeline de validação, processo e auditoria do CRUD; a demonstração customizada é somente leitura.
+
+## Auditoria e segredos
+
+CRUD oficial registra mutações bem-sucedidas em `ControleAlteracao`. Rotas privadas customizadas podem declarar `audit: { entidade: "MinhaEntidade", acao: "alterado" }`; a auditoria captura dados da resposta. Isso não equivale a uma trilha imutável de todas as tentativas ou a um histórico completo antes/depois. Não inclua credenciais no resultado auditado.
+
+`requestLog` registra requisições não-GET; `sensitiveBody: true` em mutações privadas omite corpo de entrada e resposta naquele log, inclusive nas recusas. Não cifra banco; não mascara console, URL, query string, cabeçalhos, logs de integração, auditoria nem mensagens de erro. GET não ganha proteção adicional com essa opção. A rota de PDF usa corpo sensível; o exemplo externo da Entrega 2 mantém segredo exclusivamente no ambiente backend. Persistência cifrada de credenciais é responsabilidade de um contrato disponível ou do App. [Contrato completo](PUBLIC_CONTRACTS.md).
+
+## PDF e e-mail sem infraestrutura paralela
+
+A página PDF chama `POST /recursos/pdf`, exige `pdf.render` e utiliza `capabilities.pdf.render(input, context)` com contexto autorizado, correlação e cancelamento. Sem capability resolvida retorna `PDF_RENDERING_UNAVAILABLE`. Para usar no ambiente publicado, acrescente a declaração de `oon.deploy.json` conforme [PDF_RENDERING.md](PDF_RENDERING.md); não configure endpoint/credencial de infraestrutura no App. O teste injeta transporte de PDF apenas no processo de teste, nunca no exemplo distribuído.
+
+E-mail é **opt-in separado**, para não enviar mensagens nem exigir configuração ao iniciar o exemplo. O serviço `backend/src/services/confirmacao.js` demonstra o contrato público. Chame-o de uma ação privada autorizada depois de resolver destinatário e evento de negócio no backend. A chave `eventId` deve ser estável na repetição da mesma operação; não gere uma nova chave a cada retry. O resultado `accepted`/`duplicate` indica aceite, não entrega.
+
+Para habilitar, preserve o manifesto e adicione `core.transactional-email` ao array `capabilities`, com estas configurações:
+
+```json
+{
+  "capabilitySettings": {
+    "core.transactional-email": {
+      "enabled": true,
+      "scopePolicy": "tenant_override",
+      "retentionDays": 30,
+      "attachmentsPolicy": { "allowed": false },
+      "templates": [{ "code": "confirmacao", "definition": "./backend/emails/confirmacao.json", "initialStatus": "active" }]
+    }
+  }
+}
+```
+
+O caminho acima parte do `central.app.json` na raiz e aponta para o asset já instalado **dentro de backend/**, que acompanha o empacotamento. Se o manifesto ficar dentro de backend, use `./emails/confirmacao.json`. Configure o provedor no painel `CoreTransactionalEmail`, registrando página, menu e as permissões necessárias conforme [TRANSACTIONAL_EMAIL.md](TRANSACTIONAL_EMAIL.md). Não ponha credenciais em JSON. Sem declaração o serviço recusa com `EMAIL_CAPABILITY_NOT_DECLARED`; sem configuração não há garantia de envio. Não habilite envio real em testes.
+
+## Limites de execução
+
+`recalculate: "async"` e `drainProcessJobs()` atendem recálculos do processo; a fila interna não é um contrato público durável de enqueue/claim/retry. A fila transacional de e-mail é específica de e-mail. Integrações Omie, mapeamentos fiscais, idempotência de efeitos externos, tickets e recuperação de negócio continuam no App ou em biblioteca de domínio compatível. Novas Capacidades têm acompanhamento independente e não bloqueiam a POC.
+
+## Evidências e aceite local
+
+`check:authoring` gera a base, instala o exemplo, sincroniza/verifica o cache oficial e valida typecheck/build. A jornada HTTP do backend cobre fórmulas, adulteração, validação, lookup, agregado, recálculo assíncrono, transição/bloqueio, exclusão protegida, concorrência transacional, metadata, dashboard, escopo da consulta própria, auditoria, 401/403 e PDF indisponível/transport de teste. E-mail sem declaração falha fechado; a suíte própria da capability cobre envio/idempotência com dublês. Nenhum teste envia e-mail real. Build, release npm, publicação e homologação do App são estados distintos.

package/docs/OON_APP_AGENT_GUIDE.md

@@ -1,72 +1,53 @@
 # 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.
+Roteiro da release **__OONCORE_VERSION__**. Comece por uma jornada pequena: uma pessoa abre uma página, executa uma ação e vê o resultado ou um erro útil. A árvore gerada e suas referências públicas devem ser suficientes.
 
-## 1. Gerar a base
-
-Em um diretório vazio:
+## 1. Gerar
 
 ```bash
-npx --yes --package @oondemand/create-central-oon@0.6 create-central-oon meu-app --no-install
+npx --yes --package @oondemand/create-central-oon@__OONCORE_VERSION__ create-central-oon meu-app --no-install
 cd meu-app
 npm install
-npm run ooncore:docs:check
+npm install --prefix backend
+npm install --prefix frontend
 ```
 
-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
+Use sempre o gerador oficial. Preserve o `AGENTS.md` próprio do projeto. Não copie outro App como base.
 
-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.
+## 2. Executar
 
-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.
+Requer Node compatível com os pacotes instalados e MongoDB local disponível. Configure `MONGO_URI` no arquivo abaixo para um banco de desenvolvimento.
 
-## 3. Separar os contratos
+```bash
+cp backend/.env.example backend/.env
+cp frontend/.env.example frontend/.env
+npm run dev
+```
 
-| 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 |
+O comando inicia back/front em loopback e abre uma sessão técnica local. Não é necessário cadastrar o App na Plataforma para essa execução. PDF e outras operações de plataforma podem falhar fechado; detalhes sob demanda em [LOCAL_DEVELOPMENT.md](LOCAL_DEVELOPMENT.md).
 
-`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.
+## 3. Implementar a primeira jornada
 
-## 4. Customizar
+Escolha uma intenção em [TASK_INDEX.md](TASK_INDEX.md). Para começar com página + ação + endpoint, use o exemplo de [PUBLIC_CONTRACTS.md](PUBLIC_CONTRACTS.md). Ajuste o domínio em `backend/src`, a experiência em `frontend/src` e as permissões em `central.app.json`.
 
-- 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).
+Não antecipe lista completa de funcionalidades, múltiplos épicos ou matriz final de perfis. Para uma POC controlada, use o admin já declarado e mantenha as verificações de backend. Registre próximas funções em um backlog curto.
 
-Crie apenas código de negócio. URLs internas, credenciais, registries, transports e detalhes de implementação não pertencem ao App.
+Se faltar informação, registre a lacuna, use extensão pública adequada no App e continue o que for independente. Não invente assinatura, leia internals como contrato ou remova controles de acesso para avançar.
 
-## 5. Validar
+## 4. Validar
 
 ```bash
-npm run ooncore:docs:check
-npm run ooncore:conformance
 npm run check
-npm test
+npm run build --prefix frontend
 ```
 
-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.
+`check` executa doctor, que reúne versões, lockfiles, manifestos, docs check e conformance; não é necessário repeti-los. Execute testes do App quando houver script e os testes relevantes da jornada. O scaffold neutro não cria `npm test` na raiz.
+
+Prove ação, resultado e erro pela UI/API; para mutações, confirme persistência e acesso indevido recusado. Teste local não comprova integração externa nem publicação. `context.generated.md` fica disponível apenas para referência, sem leitura integral obrigatória.
 
-## Critério final do Agent
+## 5. Publicar e validar em Dev
 
-O relato de entrega deve informar:
+Versione código, manifestos, lockfiles e o cache `.ooncore`. Publique pelo fluxo já existente do Workspace/Plataforma e confira a jornada pelo endereço público autenticado de Dev. Registre o commit publicado e o resultado. Consulte [APP_PACKAGING.md](APP_PACKAGING.md) somente para detalhes de empacotamento.
 
-- contratos públicos consultados;
-- manifestos e pontos de extensão alterados;
-- testes e gates executados;
-- limitações do runtime local;
-- qualquer lacuna documental encontrada.
+Identidade, tenancy, licenciamento, publicação e promoção são serviços homologados consumidos pelo App. Não os reimplemente nem reabra sua homologação global. Necessidade de nova Capacidade é um escopo separado. Build aprovado, publicado e homologado são estados distintos.
 
-Citar fonte privada como requisito de implementação significa que a tarefa ainda não atende a este contrato.