@oondemand/create-central-oon 0.4.30 → 0.5.1

package/README.md

@@ -36,8 +36,8 @@ Toda Central gerada possui um manifesto raiz com identidade e capabilities:
   "capabilities": ["core.collections"],
   "compatibility": {
     "core": {
-      "minVersion": "0.3.45",
-      "maxVersionExclusive": "0.4.0"
+      "minVersion": "0.5.0",
+      "maxVersionExclusive": "0.6.0"
     }
   }
 }
@@ -57,7 +57,7 @@ Responsabilidades do manifesto:
 - faixa compatível do OonCore;
 - metadados declarativos de ativação.
 
-`backend/central.config.js` fica reservado a extensões excepcionais de runtime. Em Centrais `member-central` e `portal-cockpit`, identidade, módulos e autenticação não podem ser reintroduzidos nesse arquivo. O token local de desenvolvimento é validado pelo próprio OonCore por `DEV_TOKEN`.
+`backend/central.config.js` fica reservado a extensões excepcionais de runtime. Em Centrais `member-central` e `portal-cockpit`, identidade, módulos e autenticação não podem ser reintroduzidos nesse arquivo. O desenvolvimento local usa sessão aleatória HttpOnly; tokens fixos são reprovados pela conformidade.
 
 ## Verificação de conformidade
 
@@ -87,7 +87,7 @@ O comando falha quando encontra, entre outros desvios:
 
 A CI de uma Central deve executar o comando antes do build e da publicação.
 
-## Documentação interna para Codex
+## Documentação distribuída para IA/Agents
 
 O pacote inclui documentação canônica em `docs/`. Ao criar uma Central, o CLI gera `.ooncore/` como cache local da documentação da versão instalada.
 
@@ -96,7 +96,7 @@ npm run ooncore:docs
 npm run ooncore:docs:check
 ```
 
-A pasta `.ooncore/` não é fonte de verdade; ela pode ser regenerada a partir do pacote npm.
+`.ooncore/AGENTS.md` é a entrada neutra e `.ooncore/docs/` contém os contratos completos de backend, frontend e capacidades. A pasta pode ser regenerada a partir do pacote npm sem sobrescrever o `AGENTS.md` da raiz.
 
 ## Templates funcionais
 
@@ -133,9 +133,9 @@ O bootstrap gerado importa `central.app.json` e `central.ui.json` e chama `start
 ```bash
 cd <central>
 npm run check
-
-cd backend && cp .env.example .env && npm run dev
-cd ../frontend && cp .env.example .env && npm run dev
+cp backend/.env.example backend/.env
+cp frontend/.env.example frontend/.env
+npm run dev
 ```
 
 Evoluir a Central significa declarar domínio, UI, mappings e regras específicas. O OonCore implementa como a aplicação funciona.

package/bin/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 "use strict";
 
-const { run, listTemplates, syncDocs, checkDocs } = require("../src/index");
+const { run, listTemplates, syncDocs, checkDocs, runLocalDevelopment } = require("../src/index");
 const { checkConformance } = require("../src/conformance");
 
 function parseArgs(argv) {
@@ -35,8 +35,11 @@ function parseArgs(argv) {
     else if (!arg.startsWith("-")) positionals.push(arg);
   }
 
-  if (["docs", "conformance"].includes(positionals[0])) opts.command = positionals[0];
-  else opts.name = positionals[0];
+  if (["docs", "conformance", "dev"].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;
+  } else opts.name = positionals[0];
   return opts;
 }
 
@@ -44,8 +47,9 @@ function printUsage() {
   console.error("Uso:");
   console.error("  npx create-central-oon <nome-da-central> [--template=basic]");
   console.error("  npx create-central-oon --list");
-  console.error("  npx create-central-oon docs --sync|--check");
+  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");
 }
 
 async function main() {
@@ -76,6 +80,10 @@ async function main() {
       }
       process.exit(result.ok ? 0 : 1);
     }
+    if (opts.command === "dev") {
+      runLocalDevelopment({ cwd: process.cwd() });
+      return;
+    }
     if (!opts.name) {
       printUsage();
       process.exit(1);

package/docs/ADVANCED_UX_PATTERNS.md

@@ -1,6 +1,6 @@
 # ADVANCED_UX_PATTERNS.md — UX Avançada Declarativa no OonCore
 
-Este documento orienta Codex e outras IAs a usarem o máximo de recursos do OonCore antes de criar telas customizadas. O foco é transformar padrões recorrentes de sistemas operacionais em **manifesto declarativo** e componentes reutilizáveis.
+Este documento orienta Agents a usarem o máximo de recursos do OonCore antes de criar telas customizadas. O foco é transformar padrões recorrentes de sistemas operacionais em **manifesto declarativo** e componentes reutilizáveis.
 
 ## Objetivo
 
@@ -161,7 +161,7 @@ Use componente customizado apenas quando:
 
 Mesmo nesses casos, prefira plugar o componente em uma aba `customComponent` da modal, e não substituir a página inteira.
 
-## Checklist para Codex
+## Checklist para Agents
 
 Antes de criar tela customizada:
 

package/docs/AGENTS.md

@@ -0,0 +1,47 @@
+# 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.
+
+## 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, RBAC ou integração indicados abaixo.
+6. 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 |
+|---|---|
+| 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_MANIFEST_REFERENCE.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` |
+| Integrações | `CONNECTORS_AND_INTEGRATIONS.md`, `LOCAL_SECURITY_BOUNDARY.md` |
+| Upgrade do Core | `CORE_UPGRADE.md`, `TESTING_CONFORMANCE.md`, `releases/0.5.0.md` |
+| UX avançada | `ADVANCED_UX_PATTERNS.md`, `DETAIL_MODAL_AND_RELATED_GRIDS.md`, `PORTAL_COCKPIT_PATTERNS.md` |
+
+## Fronteira obrigatória
+
+- A Central declara domínio e experiência; o Core fornece bootstrap, autenticação, ativação, RBAC, tenant, CRUD, metadata, shell, componentes genéricos, integração operacional 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
+```
+
+Se um contrato público exigir leitura do repositório privado do OonCore, registre a lacuna: a documentação distribuída está incompleta.

package/docs/AGENT_WORKFLOW.md

@@ -0,0 +1,13 @@
+# 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.
+
+Prompt operacional:
+
+> Atualize os três pacotes OonCore para a linha 0.5.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.

package/docs/AUTH_ACTIVATION_RBAC.md

@@ -0,0 +1,28 @@
+# Autenticação, ativação e RBAC
+
+## Plataforma
+
+O backend verifica o token no escopo do App, resolve tenant e acesso, aplica a política local de RBAC e cria `req.accessContext`. O frontend usa permissões somente para experiência; o backend autoriza cada operação.
+
+Ativação de plataforma cria a identidade operacional usada por integrações autorizadas. Rotas de login, launch exchange, ativação e primeiro acesso não estão disponíveis no runtime local.
+
+## Catálogo público de perfis
+
+Todo App com RBAC declarado expõe `GET /core/role-catalog`. O contrato `schemaVersion: 1` contém apenas `appCode`, `enabled` e `roles[]` com `code`, `name`, `description` e `admin`. Permissões internas não são expostas.
+
+O catálogo serve para descoberta e seleção de perfis pelo Control Plane. Ele não concede acesso: o backend consumidor deve validar `schemaVersion` e `appCode`, consultar somente o Deployment resolvido pela plataforma, revalidar o perfil antes de persistir o grant e falhar fechado quando o catálogo estiver ausente ou inválido.
+
+## Local
+
+O principal técnico é `local:developer`, sem usuário/tenant/licença na plataforma. O papel inicial é `developer` quando declarado, seguido por admin ou primeiro papel. A troca de perfil aceita apenas o manifesto e atualiza a sessão local.
+
+O estado é `ativa_local`; o `ActivationGuard` não cria nem consulta `InstanciaEcossistema`. Isso não equivale a `ativa` publicada.
+
+## Regras para extensões
+
+- use `requirePermission` em rotas customizadas;
+- derive filtros de `req.accessContext`;
+- nunca autorize por header/body de perfil ou tenant;
+- não implemente `verifyToken` em Central member/portal;
+- não persista bearer no frontend;
+- não trate simulação local como identidade operacional.

package/docs/BACKEND_API.md

@@ -0,0 +1,43 @@
+# API pública do `@oondemand/oon-core-back`
+
+Importe exclusivamente de `@oondemand/oon-core-back`. Caminhos internos não têm estabilidade garantida.
+
+## 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.
+- `activate()`: fluxo legado de ativação; não é usado no runtime local.
+- `defineCentral`, `defineModel`, `defineCollection`, `defineDocument`, `definePipeline`, `defineOmieMapping`, `defineRoutes`, `defineValidation`, `defineTrigger`: extensões imperativas suportadas.
+- `fields`: factories de campos compatíveis com schema e metadata.
+- `registry`: registry do processo; use APIs `define*`, não mutações internas.
+
+## Segurança, RBAC e tenant
+
+- `requirePermission(permission)`: middleware obrigatório em rotas sensíveis.
+- `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.
+- `scopeFilter`, `mergeScopedFilter`, `scopeMutation`, `scopedIdFilter`: aplicam isolamento aos dados. Nunca aceite tenant do body como autoridade.
+
+## Manifestos
+
+- App: `APP_MANIFEST_FILENAME`, `APP_MANIFEST_SCHEMA_VERSION`, `SUPPORTED_APP_KINDS`, `SUPPORTED_APP_MODULES`, `AppManifestError`, `validateAppManifest`, `resolveAppManifestPath`, `appManifestToConfig`, `registerAppManifest`, `loadAppManifest`.
+- Domínio: `DOMAIN_MANIFEST_FILENAME`, `DOMAIN_MANIFEST_SCHEMA_VERSION`, `SUPPORTED_DOMAIN_FIELD_KINDS`, `DOMAIN_EXPRESSION_OPERATORS`, `DomainManifestError`, `DomainRuleError`, `validateDomainManifest`, `domainManifestToDefinitions`, `registerDomainManifest`, `loadDomainManifest`, `evaluateDomainExpression`, `applyDomainMutation`, `validateDomainRecord`, `detectChangedFields`.
+- Processo: `PROCESS_MANIFEST_FILENAME`, `PROCESS_MANIFEST_SCHEMA_VERSION`, `ProcessManifestError`, `validateProcessManifest`, `registerProcessManifest`, `loadProcessManifest`, `prepareProcessMutation`, `resolveProcessBindings`, `assertReferencePolicies`, `assertAtomicInvariants`, `assertDeleteAllowed`, `recalculateDependents`, `drainProcessJobs`.
+
+Erros de manifesto carregam `code`, `statusCode` e `issues[]` com `path` e `message`.
+
+## Integrações e capabilities
+
+- `integrations`, `registerIntegrationProvider`, `enqueueIntegration`, `receiveIntegrationWebhook`.
+- `omie`, `omieModule`, `createOmieClient`, `OmieApiError`, `enqueueOmieCall`, `ensureOmieProviderRegistered`, `collectOmieDefinitions`, `describeOmieDefinitions`, `saveOmieConfiguration`, `listOmieConfigurations`, `testOmieConnection`.
+- `capabilities`, `PdfRenderingError`, `TransactionalEmailError`.
+- `operationalRequestHeaders(options)`: headers de identidade do Deployment. Retorna `LOCAL_OPERATION_NOT_SUPPORTED` no runtime local; nunca improvise identidade local.
+
+## Runtime local
+
+O namespace público `localDevelopment` expõe detecção, validação de loopback e utilitários de teste/integração do runtime. Apps consumidores normalmente apenas definem `OON_RUNTIME_MODE=local` e usam o scaffold.
+
+## Erros
+
+`GenericError(message, { statusCode, code, details })` é o erro operacional base. Rotas devem lançá-lo e deixar o middleware do Core produzir o envelope sanitizado.

package/docs/CAPABILITIES.md

@@ -0,0 +1,24 @@
+# Catálogo de capacidades do OonCore
+
+Consulte este catálogo antes de criar infraestrutura ou componentes customizados.
+
+| Capacidade | Backend | Frontend | Declaração/extensão | Local | Plataforma |
+|---|---|---|---|---|---|
+| Models e CRUD | `defineModel`, domain manifest, `/core/*` | `CoreCollection`, hooks de API | `central.domain.json`, `central.ui.json` | 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 |
+| Documentos | `defineDocument` | `CoreDocument` | UI/domain manifest | Sim | Sim |
+| Dashboards | agregações e rotas | `CoreDashboard` | UI manifest | 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/integration workers | status operacional | manifestos/hooks | Sim | Sim |
+| Integrações | runtime/provider registry | `CoreIntegration` | mapping/provider suportado | Dublê ou credencial local | Credencial operacional |
+| 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 |
+| 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.

package/docs/CODEX.md

@@ -1,83 +1,12 @@
-# CODEX.md — Regras de Codificação OonCore
+# CODEX.md — ponte de compatibilidade
 
-Este arquivo é a porta de entrada para o Codex codificar uma Central Oon.
+A fonte canônica, completa e neutra do OonCore é `AGENTS.md`.
 
-A fonte de verdade desta documentação é a versão instalada do pacote `@oondemand/create-central-oon`. A pasta `.ooncore/` gerada em cada Central é apenas um cache local, criado por `create-central-oon docs --sync`.
+Ao trabalhar em uma Central:
 
-## Antes de codificar
+1. leia primeiro o `AGENTS.md` da raiz do projeto, quando existir;
+2. leia `.ooncore/AGENTS.md`;
+3. valide `.ooncore/manifest.json` com `npm run ooncore:docs:check`;
+4. siga as referências de `.ooncore/docs/` indicadas para a tarefa.
 
-1. Rode `npm run ooncore:docs:check` na raiz da Central.
-2. Se estiver desatualizado, rode `npm run ooncore:docs`.
-3. Leia `.ooncore/context.generated.md`.
-4. Identifique o recurso do Core que resolve a necessidade antes de criar código customizado.
-
-## Leitura obrigatória por tipo de tarefa
-
-### Backend/domínio
-
-- `BACKEND_DOMAIN_MANIFEST.md`
-- `BACKEND_PATTERNS.md`
-- `COLLECTIONS_AND_PIPELINES.md`
-- `CONNECTORS_AND_INTEGRATIONS.md`
-- `RBAC_SECURITY.md`
-
-### Frontend/manifesto
-
-- `FRONTEND_PATTERNS.md`
-- `FRONTEND_MANIFEST_REFERENCE.md`
-- `REACTIVE_DOMAIN_FORMULAS.md`
-
-### UX avançada, modais, abas e itens relacionados
-
-Leia antes de criar páginas customizadas:
-
-- `ADVANCED_UX_PATTERNS.md`
-- `DETAIL_MODAL_AND_RELATED_GRIDS.md`
-
-Use estes documentos quando a necessidade envolver:
-
-- modal com abas;
-- dados principais agrupados;
-- grids relacionados;
-- edição inline;
-- ações por linha;
-- registros filhos como itens, parcelas, produtos, documentos ou pagamentos;
-- telas onde o usuário opera um registro principal e seus relacionamentos.
-
-## Princípios obrigatórios
-
-- Escreva apenas o domínio da Central.
-- Use `central.domain.json` para models, campos, fórmulas e validações cobertos pelo contrato declarativo vigente.
-- Não repita fórmulas do domínio em componentes React: os formulários do Core geram a prévia reativa a partir da metadata e o backend recalcula antes de persistir.
-- Use `@oondemand/oon-core-back` para boot, autenticação, RBAC, CRUD, metadata, auditoria e padrões de API.
-- Use `@oondemand/oon-core-front` para shell, rotas, menu, datagrid, formulários, badges, ações e renderização por metadata.
-- Não recrie infraestrutura que já existe no Core.
-- Não crie autenticação paralela.
-- Não duplique RBAC no frontend.
-- Não hardcode tenant, app, usuário, perfil, permissões, URLs sensíveis ou segredos.
-- Não exponha chaves em código, templates ou documentação gerada.
-- Não altere arquivos gerados do Core se houver extensão declarativa disponível.
-- Prefira manifestos, validations, triggers, hooks, mappings, documents, pipelines, integrations e overrides declarativos.
-- Antes de criar uma página React customizada, tente resolver com `central.ui.json`, `detailModal`, `form.groups`, `relatedGrid`, `readonlyGrid` e `rowActions`.
-
-## Ordem de decisão
-
-Ao implementar uma necessidade, siga esta ordem:
-
-1. Configuração existente do Core.
-2. Declaração em `central.config.js`, `central.domain.json` ou `central.ui.json`.
-3. Validation, trigger, hook ou mapping no backend da Central.
-4. Modal, abas, grid relacionado, ação e renderer declarativos do Core.
-5. Override local pequeno e isolado.
-6. Código customizado somente quando o Core não oferecer extensão adequada.
-
-## Entrega segura
-
-Toda alteração deve manter:
-
-- rastreabilidade;
-- validação de entrada;
-- RBAC no backend;
-- ausência de segredo hardcoded;
-- separação entre domínio da Central e infraestrutura do Core;
-- compatibilidade com atualização futura dos pacotes `@oondemand/*`.
+Não mantenha regras exclusivas neste arquivo. Codex, ChatGPT, Kimi, Manus e outros Agents devem consumir o mesmo contrato versionado.

package/docs/CORE_UPGRADE.md

@@ -0,0 +1,20 @@
+# Atualização coordenada do OonCore
+
+Os três pacotes devem permanecer na mesma linha:
+
+- `@oondemand/oon-core-back`;
+- `@oondemand/oon-core-front`;
+- `@oondemand/create-central-oon`.
+
+## Procedimento para Agent
+
+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.5.x`.
+4. Ajuste compatibilidade para `>=0.5.0 <0.6.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.
+
+Não atualize somente um pacote e não copie arquivos do Core manualmente para a Central.

package/docs/ERRORS.md

@@ -0,0 +1,18 @@
+# Contrato de erros
+
+Erros operacionais usam `{ error: { code, message, details?, requestId? } }` e status HTTP coerente.
+
+| Código | Significado |
+|---|---|
+| `LOCAL_RUNTIME_ENV_INVALID` | modo local fora de development |
+| `LOCAL_RUNTIME_PLATFORM_IDENTITY` | identidade de plataforma/Kubernetes presente |
+| `LOCAL_RUNTIME_BIND_FORBIDDEN` | bind fora de loopback |
+| `LOCAL_HOST_FORBIDDEN` / `LOCAL_ORIGIN_FORBIDDEN` | acesso de rede recusado |
+| `LOCAL_PROXY_FORBIDDEN` | tentativa de proxy no modo local |
+| `LOCAL_BOOTSTRAP_INVALID` | código ausente, reutilizado ou expirado |
+| `LOCAL_SESSION_INVALID` | cookie ausente, inválido ou expirado |
+| `LOCAL_CSRF_INVALID` | mutação sem prova CSRF |
+| `LOCAL_ROLE_NOT_DECLARED` | perfil fora do manifesto |
+| `LOCAL_OPERATION_NOT_SUPPORTED` | recurso exclusivo da plataforma |
+
+Não faça branching por texto de mensagem; use `code`. Logs e respostas nunca devem conter token, cookie, credencial, senha ou conteúdo sensível.

package/docs/FRONTEND_API.md

@@ -0,0 +1,34 @@
+# API pública do `@oondemand/oon-core-front`
+
+Importe exclusivamente da raiz do pacote.
+
+## Bootstrap e manifestos
+
+- `start`, `oonCoreFront.start`: inicialização com configuração completa.
+- `startFromManifest`, `startCentralFromManifest`, `manifestToConfig`: caminho preferencial para uma Central declarativa.
+- Tipos: `CentralUiManifest`, `CentralAppManifest`, `CentralManifestBundle`, `CentralUiOnlyManifest`, `ManifestRuntime`.
+- `ManifestRuntime.runtimeMode`: `local` usa sessão HttpOnly; `platform` usa o contrato de autenticação publicado.
+
+## Views e componentes
+
+- Definições: `defineCollectionView`, `defineDocumentView`, `definePipelineView`, `defineDashboard`, `defineOonModule`.
+- Componentes: `CoreCollection`, `CoreDocument`, `CorePipeline`, `CoreIntegration`, `CoreCurrency`, `CoreAssistant`, `CoreDashboard`, `CoreUsersAccess`, `CoreTransactionalEmail`, `CorePage`.
+- Primitivas UI v2: `CorePageHeader`, `CoreToolbar`, `CoreDataGrid`, `CoreCards`, `CoreForm`, `CoreField`, `CoreRelationField`, `CoreActions`, `CoreEmptyState`, `CoreLoadingState`.
+- Registre componentes customizados por chave em `registry`; não serialize React no JSON.
+
+## Hooks, sessão e autorização
+
+- `useOonAuth`, `can`, `PermissionGate`, `Can`: experiência baseada em permissões já resolvidas pelo backend.
+- `useOonTenant`, `createTenantStorage`: seleção de tenant; o backend continua sendo a autoridade.
+- `useOonApi`, `useOonResource`, `useCoreMetadata`, `useModelSchema`: acesso HTTP/metadata padronizado.
+- O runtime local não grava bearer no `localStorage`, envia cookie com `withCredentials` e usa CSRF double-submit nas mutações.
+
+## Domínio reativo
+
+- `DomainExpressionError`, `evaluateDomainExpression`, `applyReactiveFormulas`, `buildDomainMutationPayload`, `coerceDomainFormValue`.
+- Tipos `OonDomainExpression`, `OonComputedFieldDefinition`, `OonReactiveFormField` e `ReactiveFormulaResult`.
+- A prévia do frontend nunca substitui o recálculo e a validação do backend.
+
+## Tipos públicos
+
+Os tipos exportados incluem config, app, auth, runtime, módulos, rotas, menus, UI v1/v2, layout, registry, páginas, blocos, ações, views, campos, metadata, paginação, erros e usuário. Consulte `dist/index.d.ts` da versão instalada quando precisar da assinatura exata; ele faz parte do pacote público.

package/docs/FRONTEND_MANIFEST_REFERENCE.md

@@ -1,6 +1,6 @@
 # Referência do Manifesto Frontend OonCore
 
-Este documento é a referência operacional para o Codex criar ou alterar manifestos do frontend OonCore.
+Este documento é a referência operacional para qualquer Agent criar ou alterar manifestos do frontend OonCore.
 
 Use este arquivo junto com `FRONTEND_PATTERNS.md`. O arquivo de padrões explica como pensar a UI; este arquivo lista as opções do contrato atual e das extensões planejadas para UX avançada.
 
@@ -41,7 +41,7 @@ Existem três níveis importantes:
 2. `CentralUiManifest`: contrato lido por `startFromManifest`.
 3. `OonUiManifest` / `OonCoreFrontConfig`: contrato interno mais completo do Core Front.
 
-Para Codex, a ordem recomendada é:
+Para Agents, a ordem recomendada é:
 
 1. Começar pelo `central.ui.json`.
 2. Usar `pages` e `blocks` quando precisar de UI v2.

package/docs/LOCAL_DEVELOPMENT.md

@@ -0,0 +1,34 @@
+# Desenvolvimento local desconectado
+
+## Início
+
+```bash
+cp backend/.env.example backend/.env
+cp frontend/.env.example frontend/.env
+npm install
+npm run dev
+```
+
+O orquestrador inicia backend em `127.0.0.1:4000`, frontend em `127.0.0.1:5173`, gera códigos aleatórios e independentes para navegador e automação/seed, e abre o navegador. O Vite encaminha `/api` ao backend para manter cookies e CSRF na mesma origem.
+
+O primeiro acesso troca o código de uso único por:
+
+- cookie de sessão `HttpOnly`, `SameSite=Strict`;
+- cookie CSRF de double-submit;
+- sessão local cujo banco armazena somente hashes e expiração.
+
+O prazo padrão é 30 dias. Reiniciar o processo rotaciona o segredo sem ampliar o prazo. Excluir o banco local cria um novo período; essa limitação é aceita na linha 0.5.
+
+A decisão vem de `LocalExecutionPolicyProvider`. A fonte embarcada funciona offline e permite 30 dias. Uma fonte HTTP assinada poderá ser adicionada futuramente para novas emissões/renovações sem transformar a plataforma em dependência obrigatória.
+
+## Perfis
+
+O banner permite selecionar apenas papéis declarados em `central.app.json`. A permissão é recalculada no backend. Convites e usuários reais não são criados. Apps com tenant usam o contexto virtual fixo `local:tenant`, sem criar um tenant persistente ou aceitar um tenant arbitrário do cliente.
+
+## Integrações
+
+Use dublês ou credenciais explicitamente fornecidas no `.env` local do projeto. O Core não busca secrets da plataforma e não cria Deployment/binding/entitlement.
+
+## Encerramento
+
+`Ctrl+C` encerra os dois processos. Nunca use `--host 0.0.0.0`; conformance e startup devem reprovar essa configuração.

package/docs/LOCAL_SECURITY_BOUNDARY.md

@@ -0,0 +1,24 @@
+# Fronteira de segurança local
+
+## Garantias
+
+- bind real em loopback;
+- Host e Origin limitados a `localhost`, `127.0.0.1` e `::1`;
+- cabeçalhos de proxy recusados;
+- códigos independentes de navegador e automação/seed, aleatórios, curtos e consumidos uma vez;
+- segredo de sessão em cookie HttpOnly e somente hashes no banco;
+- logout revoga a sessão no backend e invalida cookies anteriores;
+- CSRF obrigatório nas mutações;
+- nenhum bearer local no bundle ou `localStorage`;
+- nenhuma identidade operacional ou chamada silenciosa à plataforma;
+- `operationalRequestHeaders` falha com `LOCAL_OPERATION_NOT_SUPPORTED`;
+- produção, Kubernetes e bind externo falham fechado.
+- o contexto virtual `local:tenant` isola dados locais sem criar recurso na plataforma.
+
+`Secure` é adicionado aos cookies quando `OON_LOCAL_HTTPS=true`; em HTTP loopback o cookie mantém `HttpOnly` e `SameSite=Strict`.
+
+## Limitações explícitas
+
+Quem controla código, banco e relógio locais pode reiniciar ou alterar o prazo. Os 30 dias são uma regra de experiência, não licenciamento inviolável. Uma política remota futura pode afetar novas emissões/renovações, mas não revoga imediatamente sessão offline já emitida.
+
+O objetivo de segurança é impedir exposição da máquina/rede e impedir que identidade local escape para o Ecossistema.

package/docs/METADATA_CRUD_UI.md

@@ -0,0 +1,11 @@
+# Contrato ponta a ponta de metadata, CRUD e UI
+
+1. `central.domain.json` ou `defineModel` registra model, campos, CRUD, roles e metadata.
+2. O backend expõe `/core/metadata`, `/core/models` e o router CRUD do `basePath`.
+3. Escopo de tenant/usuário, validação, fórmulas, referência, auditoria e triggers são aplicados no servidor.
+4. `central.ui.json` declara coleções, formulários, filtros, relações, esteiras, documentos e dashboards.
+5. O frontend consulta metadata e monta componentes do Core.
+
+O CRUD padrão inclui listagem paginada, leitura, criação, atualização parcial, exclusão e import/export quando habilitados. Use rota customizada somente quando a operação não puder ser representada por CRUD, ação declarativa ou processo.
+
+Campos calculados são exibidos reativamente no frontend e recalculados no backend. Campos de escopo são internos e imutáveis. Referências devem usar os filtros declarados; não faça consultas sem escopo.

package/docs/OONCORE_ARCHITECTURE.md

@@ -45,6 +45,6 @@ Cada Central começa como um mini-monolito de negócio: pequeno, coeso, isolado
 - Permissões são decididas no backend.
 - Integrações são tratadas como conectores, mappings, triggers e esteiras de integração.
 
-## Objetivo do Codex
+## Objetivo dos Agents
 
-O Codex deve acelerar a construção da Central usando a arquitetura existente. O objetivo não é gerar um app genérico, mas sim completar a camada de domínio com segurança e aderência ao Core.
+O Agent deve acelerar a construção da Central usando a arquitetura existente. O objetivo não é gerar um app genérico, mas completar a camada de domínio com segurança e aderência ao Core.

package/docs/RBAC_SECURITY.md

@@ -22,7 +22,33 @@ Use o RBAC do Core para:
 - proteger rotas;
 - permitir evolução de permissões sem reconstruir telas.
 
-## Checklist de segurança para Codex
+## Catálogo canônico de perfis
+
+```http
+GET /core/role-catalog
+```
+
+Resposta:
+
+```json
+{
+  "schemaVersion": 1,
+  "appCode": "central-compras",
+  "enabled": true,
+  "roles": [
+    {
+      "code": "viewer",
+      "name": "Consulta",
+      "description": "Somente leitura.",
+      "admin": false
+    }
+  ]
+}
+```
+
+Use esse endpoint para montar seletores e validar grants por App. Não mantenha códigos de perfil paralelos no frontend ou no Control Plane. O consumidor deve validar versão e App, bloquear redirects e destinos de rede privados, revalidar o perfil no backend e tratar catálogo inválido como indisponível. O endpoint usa cache público de cinco minutos e nunca expõe a lista de permissões; a autorização efetiva continua no App.
+
+## Checklist de segurança para Agents
 
 Antes de concluir uma alteração, confirme:
 

package/docs/ROUTES_HOOKS_WORKERS.md

@@ -0,0 +1,11 @@
+# Rotas, hooks, triggers e workers
+
+- `defineRoutes(basePath, router)`: registra rota específica do domínio. Proteja com auth já montada, `requirePermission`, validação e `req.accessContext`.
+- `defineValidation(model, fn)`: valida o estado consolidado antes de persistir.
+- `defineTrigger(model, fn)`: efeito de domínio rastreável associado à mutação.
+- Process manifest: transições, bindings, invariantes, recálculos e jobs transacionais.
+- Integration runtime: outbox/inbox, retry, lock, idempotência, histórico e webhook.
+
+Não crie processo web paralelo, registry local, timer genérico ou worker que replique o Core. Jobs devem ser idempotentes, limitar retry, sanitizar payload/erro e encerrar com o lifecycle do processo.
+
+No runtime local, workers e filas podem operar contra Mongo local, mas operações que exigem identidade da plataforma devem retornar `LOCAL_OPERATION_NOT_SUPPORTED`.

package/docs/RUNTIME_MODES.md

@@ -0,0 +1,16 @@
+# Modos de runtime
+
+| Contrato | `local` | `platform` |
+|---|---|---|
+| Configuração | `NODE_ENV=development`, `OON_RUNTIME_MODE=local` | ambiente publicado |
+| Bind | somente loopback | contrato da infraestrutura |
+| Identidade | principal técnico local | usuário/tenant/Deployment reais |
+| Ativação | `ativa_local` | estados da plataforma |
+| Sessão | cookie HttpOnly, TTL de até 30 dias | auth/SSO configurado |
+| RBAC | simula somente papéis do manifesto | acessos reais |
+| Plataforma | nenhuma chamada obrigatória | conforme capability |
+| Publicar/promover | bloqueado | por contratos autorizados |
+
+`local` não é o ambiente publicado `desenvolvimento`. Ele não possui `deploymentId`, `instanceId`, `bindingId`, `entitlementId`, licença ou credencial operacional.
+
+O Core falha no startup local quando encontra produção, Kubernetes, identidade operacional, bind não-loopback ou `PUBLIC_APP_URL` externa.

package/docs/TESTING_CONFORMANCE.md

@@ -0,0 +1,30 @@
+# Testes e conformidade
+
+## Gates do projeto consumidor
+
+```bash
+npm run ooncore:docs:check
+npm run ooncore:conformance
+npm run check
+npm test
+```
+
+## Runtime local
+
+Comprove:
+
+- `127.0.0.1` e `localhost` funcionam;
+- `0.0.0.0`, IP de LAN, Host/Origin externos e proxy falham;
+- nenhuma chamada alcança a plataforma;
+- cookies existem e bearer não aparece no `localStorage`;
+- bootstraps de navegador e automação não podem ser reutilizados nem invalidar um ao outro;
+- expiração bloqueia a sessão e reiniciar o processo não amplia o prazo;
+- Apps multi-tenant recebem somente o contexto virtual fixo `local:tenant`;
+- perfis fora do manifesto falham;
+- CRUD, metadata, dashboards, processos e integrações locais funcionam;
+- `operationalRequestHeaders` falha fechado;
+- apagar o Mongo local inicia novo prazo, como limitação documentada.
+
+## Documentação
+
+`docs --check` valida fonte, versão, schema, entrada `AGENTS.md`, hashes dos documentos e entrypoints, além da presença de todos os arquivos. O tarball npm deve conter docs, templates e schemas. Exemplos devem compilar ou executar em CI.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,18 @@
+# Troubleshooting
+
+| Sintoma | Verificação | Correção |
+|---|---|---|
+| `LOCAL_RUNTIME_ENV_INVALID` | `NODE_ENV` | use `development` |
+| bind proibido | `HOST`, Vite `server.host` | use `127.0.0.1` |
+| bootstrap inválido | URL antiga/reutilizada | reinicie `npm run dev` e use a nova URL |
+| 401 local | cookie apagado/expirado | abra a URL de bootstrap atual |
+| `LOCAL_SESSION_EXPIRED` no startup | prazo local de 30 dias encerrado | exclua os dados locais para iniciar o período aceito na linha 0.5 |
+| seed invalida o navegador | código incorreto usado no script | use exclusivamente o código **Automação/seed** |
+| 403 CSRF | frontend não está na mesma origem/proxy | use `/api` pelo proxy Vite |
+| docs desatualizados | versão/hash | `npm run ooncore:docs` |
+| perfil ausente | `central.app.json.rbac.roles` | declare o papel e sincronize/reinicie |
+| operação de plataforma bloqueada | código `LOCAL_OPERATION_NOT_SUPPORTED` | use dublê/credencial local ou homologue publicado |
+| Mongo indisponível | `MONGO_URI`, replica set quando exigido | inicie Mongo local conforme o projeto |
+| porta ocupada | 4000/5173 | encerre processo conflitante; não exponha outra interface |
+
+Nunca resolva erro local adicionando token fixo, `0.0.0.0`, proxy externo ou credencial de Deployment.

package/docs/releases/0.5.0.md

@@ -0,0 +1,25 @@
+# OonCore 0.5.0
+
+## Mudança principal
+
+Runtime de desenvolvimento local desconectado, com sessão automática por até 30 dias, loopback obrigatório e documentação canônica distribuída para IA/Agents.
+
+## Migração obrigatória
+
+- alinhar back, front e create-central em `0.5.x`;
+- usar `OON_RUNTIME_MODE=local` apenas com `NODE_ENV=development`;
+- remover `DEV_TOKEN`, `VITE_DEV_TOKEN` e o valor `dev-local`;
+- usar Vite em `127.0.0.1` com proxy `/api`;
+- sincronizar `.ooncore/` e preservar o `AGENTS.md` raiz;
+- usar o código dedicado de automação para seed, preservando o bootstrap do navegador;
+- atualizar compatibilidade do App para `>=0.5.0 <0.6.0` após homologação.
+
+## Segurança
+
+Local não emite nem reutiliza identidade operacional. Rotas de plataforma são bloqueadas; cookies/CSRF substituem bearer local. Apps com tenant usam apenas `local:tenant`. Reiniciar processos não renova uma sessão expirada; reset do banco reinicia o prazo e permanece uma limitação conhecida.
+
+O manifesto documental inclui hash dos documentos e dos entrypoints gerados (`AGENTS.md`, `CODEX.md` e `context.generated.md`).
+
+## Compatibilidade
+
+`DEV_TOKEN` explícito permanece temporariamente apenas para testes/CI legados fora de `OON_RUNTIME_MODE=local`; novos scaffolds não o geram.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@oondemand/create-central-oon",
-  "version": "0.4.30",
+  "version": "0.5.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oondemand/oon-platform.git",
     "directory": "packages/create-central-oon"
   },
-  "description": "Gerador de Centrais Oon com contratos declarativos, guardrails de conformidade e documentação interna para Codex.",
+  "description": "Gerador de Centrais Oon com contratos declarativos, runtime local e documentação versionada para IA/Agents.",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",

package/src/conformance.js

@@ -197,6 +197,7 @@ function checkBootstrap(root, files, issues) {
     (candidate) => candidate.startsWith("frontend/src/")
       && candidate !== file
       && candidate !== "frontend/src/vite-env.d.ts"
+      && path.basename(candidate) !== ".gitkeep"
       && !(portalCockpit && isPortalExtension(candidate)),
   );
   for (const extra of extraFrontendSources) {
@@ -270,6 +271,23 @@ function checkAllowedExtensions(files, issues) {
   }
 }
 
+function checkLocalRuntimeSafety(root, files, issues) {
+  const checks = [
+    { pattern: /\b(?:VITE_)?DEV_TOKEN\b/, code: "LOCAL_FIXED_TOKEN", message: "token local fixo não é permitido; use a sessão automática do OonCore." },
+    { pattern: /["']dev-local["']/, code: "LOCAL_PREDICTABLE_TOKEN", message: "credencial previsível dev-local não é permitida." },
+    { pattern: /\bhost\s*:\s*["'](?:0\.0\.0\.0|::)["']/, code: "LOCAL_BIND_EXTERNAL", message: "servidor de desenvolvimento deve usar 127.0.0.1." },
+  ];
+  const candidates = files.filter((file) =>
+    /(?:^|\/)(?:env\.example|\.env\.example|vite\.config\.[cm]?[jt]s|main\.[jt]sx?|package\.json)$/.test(file),
+  );
+  for (const file of candidates) {
+    const source = readText(root, file);
+    for (const check of checks) {
+      if (check.pattern.test(source)) addIssue(issues, check.code, file, check.message);
+    }
+  }
+}
+
 function checkConformance({ cwd = process.cwd() } = {}) {
   const root = path.resolve(cwd);
   const files = listFiles(root);
@@ -280,6 +298,7 @@ function checkConformance({ cwd = process.cwd() } = {}) {
   checkDomainManifest(root, issues);
   checkExecutableFiles(root, files, issues);
   checkAllowedExtensions(files, issues);
+  checkLocalRuntimeSafety(root, files, issues);
   return { ok: issues.length === 0, root, filesChecked: files.length, issues };
 }
 

package/src/dev.js

@@ -0,0 +1,77 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const { spawn } = require("node:child_process");
+const path = require("node:path");
+const fs = require("node:fs");
+
+function npmCommand() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+function openBrowser(url) {
+  const command = process.platform === "win32"
+    ? ["cmd", ["/c", "start", "", url]]
+    : process.platform === "darwin"
+      ? ["open", [url]]
+      : ["xdg-open", [url]];
+  const child = spawn(command[0], command[1], { detached: true, stdio: "ignore" });
+  child.on("error", () => {});
+  child.unref();
+}
+
+function runLocalDevelopment({ cwd = process.cwd(), open = true } = {}) {
+  const root = path.resolve(cwd);
+  for (const directory of ["backend", "frontend"]) {
+    if (!fs.existsSync(path.join(root, directory, "package.json"))) {
+      throw new Error(`Projeto inválido: ${directory}/package.json não encontrado.`);
+    }
+  }
+
+  const bootstrapCode = crypto.randomBytes(32).toString("base64url");
+  const automationBootstrapCode = crypto.randomBytes(32).toString("base64url");
+  const env = {
+    ...process.env,
+    NODE_ENV: "development",
+    OON_RUNTIME_MODE: "local",
+    OON_LOCAL_BOOTSTRAP_CODE: bootstrapCode,
+    OON_LOCAL_AUTOMATION_BOOTSTRAP_CODE: automationBootstrapCode,
+  };
+  const children = ["backend", "frontend"].map((directory) => spawn(
+    npmCommand(),
+    ["run", "dev", "--prefix", directory],
+    { cwd: root, env, stdio: "inherit" },
+  ));
+
+  const url = `http://127.0.0.1:5173/?oon_local_bootstrap=${bootstrapCode}`;
+  console.log("\nOonCore local desconectado");
+  console.log(`Frontend: ${url}`);
+  console.log("Backend:  http://127.0.0.1:4000");
+  console.log(`Automação/seed: ${automationBootstrapCode}`);
+  if (open) setTimeout(() => openBrowser(url), 2500).unref();
+
+  let stopping = false;
+  function stop(signal = "SIGTERM") {
+    if (stopping) return;
+    stopping = true;
+    for (const child of children) if (!child.killed) child.kill(signal);
+  }
+  process.once("SIGINT", () => stop("SIGINT"));
+  process.once("SIGTERM", () => stop("SIGTERM"));
+  for (const child of children) {
+    child.once("exit", (code) => {
+      if (!stopping && code) {
+        stop();
+        process.exitCode = code;
+      }
+    });
+    child.once("error", (error) => {
+      console.error("Falha ao iniciar runtime local:", error.message);
+      stop();
+      process.exitCode = 1;
+    });
+  }
+  return { children, url, automationBootstrapCode, stop };
+}
+
+module.exports = { runLocalDevelopment, openBrowser };

package/src/index.js

@@ -5,6 +5,7 @@ const path = require("node:path");
 const crypto = require("node:crypto");
 const { spawnSync } = require("node:child_process");
 const { copyTemplate } = require("./render");
+const { runLocalDevelopment } = require("./dev");
 
 const PACKAGE_ROOT = path.join(__dirname, "..");
 const TEMPLATES_DIR = path.join(PACKAGE_ROOT, "templates");
@@ -90,6 +91,49 @@ function docsHash(files = listDocFiles()) {
   return hash.digest("hex");
 }
 
+function copiedDocsHash(docsDir, files) {
+  const hash = crypto.createHash("sha256");
+  for (const file of files) {
+    const normalized = file.split(path.sep).join("/");
+    const absolute = path.join(docsDir, file);
+    if (!fs.existsSync(absolute)) return null;
+    hash.update(normalized);
+    hash.update("\n");
+    hash.update(fs.readFileSync(absolute));
+    hash.update("\n");
+  }
+  return hash.digest("hex");
+}
+
+function entrypointContents(files = listDocFiles()) {
+  return {
+    "AGENTS.md": fs.readFileSync(path.join(DOCS_DIR, "AGENTS.md"), "utf8"),
+    "CODEX.md": fs.readFileSync(path.join(DOCS_DIR, "CODEX.md"), "utf8"),
+    "context.generated.md": buildContext(files),
+  };
+}
+
+function contentMapHash(entries) {
+  const hash = crypto.createHash("sha256");
+  for (const [name, content] of Object.entries(entries).sort(([a], [b]) => a.localeCompare(b))) {
+    hash.update(name);
+    hash.update("\n");
+    hash.update(content);
+    hash.update("\n");
+  }
+  return hash.digest("hex");
+}
+
+function copiedEntrypointsHash(outDir, names) {
+  const entries = {};
+  for (const name of names) {
+    const absolute = path.join(outDir, name);
+    if (!fs.existsSync(absolute)) return null;
+    entries[name] = fs.readFileSync(absolute, "utf8");
+  }
+  return contentMapHash(entries);
+}
+
 function resolveCentralRoot(cwd = process.cwd()) {
   const current = path.resolve(cwd);
   const parent = path.dirname(current);
@@ -134,12 +178,12 @@ function copyDocs(srcDir, destDir) {
 
 function buildContext(files = listDocFiles()) {
   const header = [
-    "# OonCore Contexto Consolidado para Codex",
+    "# OonCore — Contexto consolidado para IA/Agents",
     "",
-    "> Arquivo gerado automaticamente por `create-central-oon docs --sync`.",
+    "> Arquivo gerado automaticamente por `create-central-oon docs sync`.",
     "> Não edite manualmente. A fonte de verdade está no pacote `@oondemand/create-central-oon` instalado.",
     "",
-    "Este contexto consolida as regras mínimas para codificar Centrais Oon com segurança, usando o máximo dos recursos do OonCore.",
+    "Este contexto consolida os contratos públicos para Codex, ChatGPT, Kimi, Manus ou qualquer Agent compatível.",
     "",
   ].join("\n");
 
@@ -162,12 +206,15 @@ function buildContext(files = listDocFiles()) {
 }
 
 function buildManifest(files = listDocFiles()) {
+  const entrypoints = entrypointContents(files);
   return {
+    schemaVersion: 1,
     source: "@oondemand/create-central-oon",
     version: readPackageVersion(),
-    generatedAt: new Date().toISOString(),
     docsMode: "generated-cache",
+    entrypoint: "AGENTS.md",
     docsHash: docsHash(files),
+    entrypointsHash: contentMapHash(entrypoints),
     files: files.map((file) => file.split(path.sep).join("/")),
   };
 }
@@ -186,9 +233,9 @@ function syncDocs(opts = {}) {
   removeDir(docsOutDir);
   copyDocs(DOCS_DIR, docsOutDir);
 
-  const codexSource = path.join(DOCS_DIR, "CODEX.md");
-  if (fs.existsSync(codexSource)) {
-    fs.copyFileSync(codexSource, path.join(outDir, "CODEX.md"));
+  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, "context.generated.md"), buildContext(files));
@@ -205,6 +252,8 @@ function checkDocs(opts = {}) {
   const version = readPackageVersion();
   const files = listDocFiles();
   const currentHash = docsHash(files);
+  const expectedEntrypoints = entrypointContents(files);
+  const expectedEntrypointsHash = contentMapHash(expectedEntrypoints);
 
   if (!fs.existsSync(manifestPath)) {
     throw new Error("Documentação OonCore local não encontrada. Rode `npm run ooncore:docs`.");
@@ -217,6 +266,10 @@ function checkDocs(opts = {}) {
     problems.push(`fonte esperada @oondemand/create-central-oon, encontrada ${manifest.source || "(vazia)"}`);
   }
 
+  if (manifest.schemaVersion !== 1 || manifest.entrypoint !== "AGENTS.md") {
+    problems.push("manifesto documental não possui schemaVersion=1 e entrypoint=AGENTS.md");
+  }
+
   if (manifest.version !== version) {
     problems.push(`versão local ${manifest.version || "(vazia)"} diferente da instalada ${version}`);
   }
@@ -225,6 +278,27 @@ function checkDocs(opts = {}) {
     problems.push("hash da documentação local diferente da documentação instalada");
   }
 
+  if (manifest.entrypointsHash !== expectedEntrypointsHash) {
+    problems.push("hash dos entrypoints gerados diferente da documentação instalada");
+  }
+
+  const localHash = copiedDocsHash(path.join(root, ".ooncore", "docs"), files);
+  if (!localHash || localHash !== manifest.docsHash) {
+    problems.push("arquivos de .ooncore/docs estão ausentes ou foram alterados");
+  }
+
+  const entrypointNames = Object.keys(expectedEntrypoints);
+  for (const entrypoint of entrypointNames) {
+    if (!fs.existsSync(path.join(root, ".ooncore", entrypoint))) {
+      problems.push(`entrada obrigatória ausente: .ooncore/${entrypoint}`);
+    }
+  }
+
+  const localEntrypointsHash = copiedEntrypointsHash(path.join(root, ".ooncore"), entrypointNames);
+  if (!localEntrypointsHash || localEntrypointsHash !== manifest.entrypointsHash) {
+    problems.push("entrypoints de .ooncore estão ausentes ou foram alterados");
+  }
+
   if (problems.length) {
     throw new Error(`Documentação OonCore desatualizada:\n- ${problems.join("\n- ")}\nRode \`npm run ooncore:docs\`.`);
   }
@@ -261,7 +335,7 @@ async function run(opts) {
   // 2. Overlay do template escolhido (vence sobre o _base).
   copyTemplate(path.join(TEMPLATES_DIR, template.id), targetDir, tokens);
 
-  // 3. Contexto local para Codex derivado da documentação da versão instalada.
+  // 3. Contexto local neutro para Agents derivado da versão instalada.
   syncDocs({ cwd: targetDir });
 
   console.log("✔ Arquivos gerados.");
@@ -289,15 +363,12 @@ function printNextSteps(tokens, opts) {
 ✅ Central "${tokens.name}" pronta.
 
 Próximos passos:
-${cd}  # Sincronizar/validar documentação local do Core para Codex
+${cd}  # Sincronizar/validar documentação local do Core para Agents
   npm run ooncore:docs
   npm run ooncore:docs:check
 
-  # Backend (só domínio — models/validations/triggers/...)
-  cd backend && cp .env.example .env && npm run dev
-
-  # Frontend (só declaração — central.ui.json)
-  cd ../frontend && cp .env.example .env && npm run dev
+  # Runtime local desconectado (backend + frontend)
+  npm run dev
 
 O backend expõe /core/metadata; o frontend renderiza as telas a partir dele.
 Edite backend/src/models e frontend/central.ui.json para evoluir a Central.
@@ -313,4 +384,5 @@ module.exports = {
   syncDocs,
   checkDocs,
   resolveCentralRoot,
+  runLocalDevelopment,
 };

package/templates/_base/README.md

@@ -29,11 +29,12 @@ A pasta `.ooncore/` é um cache regenerável da documentação publicada no paco
 npm install
 npm run check
 
-cd backend && cp .env.example .env && npm install && npm run dev
-cd ../frontend && cp .env.example .env && npm install && npm run dev
+cp backend/.env.example backend/.env
+cp frontend/.env.example frontend/.env
+npm run dev
 ```
 
-Em desenvolvimento, configure o mesmo valor em `DEV_TOKEN` no backend e `VITE_DEV_TOKEN` no frontend. A validação do token local é fornecida pelo Core; não implemente `auth.verifyToken` 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. Não implemente autenticação ou ativação paralela na Central.
 
 ## Evoluindo a Central
 

package/templates/_base/backend/env.example

@@ -3,19 +3,12 @@ SERVICE_NAME=__SLUG__
 SERVICE_VERSION=0.1.0
 PORT=4000
 NODE_ENV=development
+OON_RUNTIME_MODE=local
 
 # Banco
 MONGO_URI=mongodb://localhost:27017/__SLUG__
 
-# Autenticacao e autorizacao pela Central de Ativacoes
-# URL publica/frontend da Central de Ativacoes.
-CENTRAL_ATIVACAO_URL=https://central-ativacao.central.oondemand.online
-# URL canonica do backend/API da Central de Ativacoes.
-CENTRAL_ATIVACAO_API_URL=https://central-ativacao.central.oondemand.online/api/
 APP_CODE=__SLUG__
-AUTH_PROVIDER_TIMEOUT_MS=10000
-# Compatibilidade temporaria: CENTRAL_ATIVACAO_BACKEND_URL, MEUS_APPS_BACKEND_URL e APP_KEY tambem sao aceitas.
 
-# Token de desenvolvimento local quando a Central sobrescrever verifyToken.
-# Deve ser igual ao VITE_DEV_TOKEN configurado no frontend.
-DEV_TOKEN=dev-local
+# O runtime local cria uma sessão aleatória por 30 dias e escuta apenas em loopback.
+# Não configure credenciais, URLs ou tokens da plataforma neste arquivo.

package/templates/_base/backend/package.json

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

package/templates/_base/central.app.json

@@ -24,8 +24,8 @@
   ],
   "compatibility": {
     "core": {
-      "minVersion": "0.3.45",
-      "maxVersionExclusive": "0.5.0"
+      "minVersion": "0.5.0",
+      "maxVersionExclusive": "0.6.0"
     }
   },
   "activation": {

package/templates/_base/frontend/env.example

@@ -1,9 +1,3 @@
-# URL do backend da Central (oonCore-back)
-VITE_API_URL=http://localhost:4000
-
-# Opcional: login externo/SSO. Sem essa variável, o Core usa /login.
-# VITE_MEUS_APPS_URL=https://login.example.com
-
-# Desenvolvimento local: deve ser igual ao DEV_TOKEN do backend.
-# O frontend envia este token para /auth/validar-token antes de qualquer redirect.
-VITE_DEV_TOKEN=dev-local
+# O Vite encaminha /api ao backend em 127.0.0.1:4000.
+# Não configure token ou URL da plataforma para desenvolvimento local.
+VITE_API_URL=/api

package/templates/_base/frontend/package.json

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

package/templates/_base/frontend/src/main.tsx

@@ -3,7 +3,7 @@ import app from "../../central.app.json";
 import ui from "../central.ui.json";
 
 startCentralFromManifest({ app, ui }, {
-  apiBaseUrl: import.meta.env.VITE_API_URL ?? "http://localhost:4000",
-  meusAppsUrl: import.meta.env.VITE_MEUS_APPS_URL,
-  devToken: import.meta.env.DEV ? (import.meta.env.VITE_DEV_TOKEN ?? "dev-local") : undefined,
+  apiBaseUrl: import.meta.env.VITE_API_URL ?? "/api",
+  runtimeMode: import.meta.env.DEV ? "local" : "platform",
+  meusAppsUrl: import.meta.env.DEV ? undefined : import.meta.env.VITE_MEUS_APPS_URL,
 });

package/templates/_base/frontend/vite.config.ts

@@ -4,7 +4,16 @@ import react from "@vitejs/plugin-react";
 export default defineConfig({
   plugins: [react()],
   server: {
+    host: "127.0.0.1",
     port: 5173,
+    strictPort: true,
+    proxy: {
+      "/api": {
+        target: "http://127.0.0.1:4000",
+        changeOrigin: false,
+        rewrite: (path) => path.replace(/^\/api/, ""),
+      },
+    },
     fs: { allow: [".."] },
   },
 });

package/templates/_base/package.json

@@ -4,14 +4,15 @@
   "private": true,
   "description": "Central Oon __NAME__ gerada com create-central-oon.",
   "scripts": {
-    "ooncore:docs": "create-central-oon docs --sync",
-    "ooncore:docs:check": "create-central-oon docs --check",
+    "ooncore:docs": "create-central-oon docs sync",
+    "ooncore:docs:check": "create-central-oon docs check",
     "ooncore:conformance": "create-central-oon conformance",
     "check": "npm run ooncore:docs:check && npm run ooncore:conformance",
+    "dev": "create-central-oon dev",
     "dev:backend": "npm run dev --prefix backend",
     "dev:frontend": "npm run dev --prefix frontend"
   },
   "devDependencies": {
-    "@oondemand/create-central-oon": "0.4.30"
+    "@oondemand/create-central-oon": "0.5.1"
   }
 }