@oondemand/create-central-oon 0.3.8 → 0.3.9

package/README.md

@@ -1,9 +1,9 @@
 # @oondemand/create-central-oon
 
-📖 **[Documentação completa → ooncoredoc.vercel.app](https://ooncoredoc.vercel.app)**
-
 Gerador de **Centrais Oon**. Cria, a partir do nome da Central, um `backend/` de domínio e um `frontend/` declarativo prontos para consumir o Core (`@oondemand/oon-core-back` e `@oondemand/oon-core-front`).
 
+> A documentação pública pode existir para consulta, mas a fonte de verdade para codificação assistida fica dentro deste pacote npm, versionada junto com o gerador.
+
 Toda Central gerada nasce com o padrão visual e operacional consolidado na **Central Minexco**:
 
 - identidade visual Oon/CST com Poppins, azul `#0474AF` e fundo `#F8F9FA`;
@@ -36,6 +36,51 @@ Aliases: o binário também responde por `scaffold-central-oon`.
 | `--no-install`   | Não roda `npm install` nos projetos gerados.                  |
 | `--list`         | Lista os templates e sai.                                     |
 
+## Documentação interna para Codex
+
+O pacote inclui documentação canônica em `docs/`. Ela é publicada no npm junto com o gerador.
+
+Ao criar uma Central, o CLI gera uma pasta `.ooncore/` com um cache local da documentação da versão instalada:
+
+```txt
+<central>/
+└── .ooncore/
+    ├── CODEX.md
+    ├── context.generated.md
+    ├── manifest.json
+    └── docs/
+```
+
+A pasta `.ooncore/` não é a fonte de verdade. Ela é apenas o contexto local para o Codex trabalhar sem depender de site externo.
+
+### Sincronizar documentação local
+
+Na raiz da Central:
+
+```bash
+npm run ooncore:docs
+```
+
+ou diretamente:
+
+```bash
+npx create-central-oon docs --sync
+```
+
+### Verificar se está atualizada
+
+```bash
+npm run ooncore:docs:check
+```
+
+ou diretamente:
+
+```bash
+npx create-central-oon docs --check
+```
+
+O check compara a versão e o hash da documentação local com a versão instalada do pacote.
+
 ## Templates funcionais
 
 Todos utilizam o mesmo frontend padrão Minexco.
@@ -55,6 +100,8 @@ Todos utilizam o mesmo frontend padrão Minexco.
 ```txt
 <central>/
 ├── README.md
+├── package.json              # scripts de sync/check da documentação OonCore
+├── .ooncore/                 # cache local gerado a partir do pacote instalado
 ├── backend/                  # consome @oondemand/oon-core-back
 │   ├── central.config.js     # identidade + módulos + paths de domínio
 │   ├── central.manifest.json # valores de deploy (render no Core)
@@ -70,8 +117,11 @@ Todos utilizam o mesmo frontend padrão Minexco.
 ## Próximos passos após gerar
 
 ```bash
-cd <central>/backend  && cp .env.example .env && npm run dev
-cd ../frontend        && cp .env.example .env && npm run dev
+cd <central>
+npm run ooncore:docs:check
+
+cd backend  && cp .env.example .env && npm run dev
+cd ../frontend && cp .env.example .env && npm run dev
 ```
 
 Evoluir a Central significa criar models em `backend/src/models` e declarar as telas em `frontend/central.ui.json`. Menu, rotas, datagrids, formulários e esteiras são montados pelo Core mantendo o padrão Minexco.

package/bin/cli.js

@@ -2,9 +2,11 @@
 "use strict";
 
 /**
- * CLI do create-central-oon (Fase 4 — Seção 5/25).
+ * CLI do create-central-oon.
  *
  *   npx create-central-oon <nome-da-central> [opções]
+ *   npx create-central-oon docs --sync
+ *   npx create-central-oon docs --check
  *
  * Opções:
  *   --template=<t>   Template inicial (default: basic). Veja --list.
@@ -12,26 +14,62 @@
  *   --force          Sobrescreve pasta existente.
  *   --no-install     Não roda npm install nos projetos gerados.
  *   --list           Lista os templates disponíveis e sai.
+ *
+ * Documentação:
+ *   docs --sync      Gera/atualiza .ooncore/ com a documentação da versão instalada.
+ *   docs --check     Valida se .ooncore/ está sincronizado com a versão instalada.
  */
 
-const { run, listTemplates } = require("../src/index");
+const { run, listTemplates, syncDocs, checkDocs } = require("../src/index");
 
 function parseArgs(argv) {
-  const opts = { template: "basic", here: false, force: false, install: true, list: false };
+  const opts = {
+    command: null,
+    template: "basic",
+    here: false,
+    force: false,
+    install: true,
+    list: false,
+    docsSync: false,
+    docsCheck: false,
+  };
   const positionals = [];
-  for (const arg of argv) {
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
     if (arg === "--here") opts.here = true;
     else if (arg === "--force") opts.force = true;
     else if (arg === "--no-install") opts.install = false;
     else if (arg === "--list") opts.list = true;
+    else if (arg === "--sync") opts.docsSync = true;
+    else if (arg === "--check") opts.docsCheck = true;
     else if (arg.startsWith("--template=")) opts.template = arg.slice("--template=".length);
-    else if (arg === "--template") opts.template = argv[argv.indexOf(arg) + 1];
-    else if (!arg.startsWith("-")) positionals.push(arg);
+    else if (arg === "--template") {
+      opts.template = argv[i + 1];
+      i += 1;
+    } else if (!arg.startsWith("-")) {
+      positionals.push(arg);
+    }
   }
-  opts.name = positionals[0];
+
+  if (positionals[0] === "docs") {
+    opts.command = "docs";
+  } else {
+    opts.name = positionals[0];
+  }
+
   return opts;
 }
 
+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");
+  console.error("  npx create-central-oon docs --check");
+}
+
 async function main() {
   const opts = parseArgs(process.argv.slice(2));
 
@@ -41,13 +79,21 @@ async function main() {
     process.exit(0);
   }
 
-  if (!opts.name) {
-    console.error("Uso: npx create-central-oon <nome-da-central> [--template=basic]");
-    console.error("     npx create-central-oon --list");
-    process.exit(1);
-  }
-
   try {
+    if (opts.command === "docs") {
+      if (opts.docsCheck) {
+        checkDocs();
+      } else {
+        syncDocs();
+      }
+      return;
+    }
+
+    if (!opts.name) {
+      printUsage();
+      process.exit(1);
+    }
+
     await run(opts);
   } catch (err) {
     console.error("\n✖", err.message);

package/docs/BACKEND_PATTERNS.md

@@ -0,0 +1,87 @@
+# Padrões Backend
+
+O backend da Central deve conter apenas domínio e extensões. Boot, infraestrutura, CRUD padrão, autenticação, RBAC e metadata pertencem ao `@oondemand/oon-core-back`.
+
+## Estrutura esperada
+
+```txt
+backend/
+├── central.config.js
+├── central.manifest.json
+└── src/
+    ├── models/
+    ├── validations/
+    ├── triggers/
+    ├── hooks/
+    ├── mappings/
+    ├── documents/
+    ├── pipelines/
+    ├── integrations/
+    ├── routes/
+    ├── controllers/
+    └── services/
+```
+
+## Models
+
+Use models para declarar entidades de negócio. Cada model deve ser pequeno, com nomes claros e campos compatíveis com as telas e integrações.
+
+Boas práticas:
+
+- use campos explícitos;
+- defina tipos, obrigatoriedade e enums quando aplicável;
+- preserve campos de status para esteiras;
+- evite regras complexas diretamente no schema;
+- evite dependência direta de frontend.
+
+## Validations
+
+Use validations para regras de negócio síncronas e mensagens claras para o usuário.
+
+Exemplos:
+
+- campo obrigatório condicional;
+- status permitido para transição;
+- valor mínimo/máximo;
+- combinação inválida de campos;
+- bloqueio por permissão ou perfil.
+
+## Triggers e hooks
+
+Use triggers e hooks para efeitos controlados depois ou antes de alterações.
+
+Exemplos:
+
+- criar ticket de integração;
+- recalcular campos derivados;
+- gerar histórico operacional;
+- disparar conector;
+- atualizar etapa da esteira.
+
+Regras:
+
+- trigger não deve esconder regra crítica sem validação;
+- evite efeitos irreversíveis sem log;
+- integração externa deve passar por camada de integração/conector;
+- falhas de integração devem gerar status rastreável, não quebrar silenciosamente o processo.
+
+## Rotas customizadas
+
+Crie rotas customizadas somente quando o CRUD/metadata do Core não resolver.
+
+Toda rota customizada deve ter:
+
+- autenticação;
+- verificação de permissão;
+- validação de entrada;
+- tratamento de erro;
+- resposta padronizada;
+- ausência de segredo hardcoded.
+
+## Serviços
+
+Use `services/` para regras reutilizáveis. Evite controllers grandes.
+
+## Segurança
+
+Nunca confie no frontend para permissão, tenant, app ou perfil. O backend deve validar tudo que altera dados, dispara integrações ou expõe informações sensíveis.

package/docs/CHECKLIST_IMPLEMENTACAO.md

@@ -0,0 +1,41 @@
+# Checklist de Implementação
+
+Use este checklist antes de concluir qualquer tarefa de codificação em uma Central Oon.
+
+## Contexto
+
+- [ ] Rodei `npm run ooncore:docs:check`.
+- [ ] Rodei `npm run ooncore:docs` se havia documentação desatualizada.
+- [ ] Li `.ooncore/context.generated.md`.
+- [ ] Entendi qual recurso do Core já resolve parte da necessidade.
+
+## Backend
+
+- [ ] Usei model, validation, trigger, hook, mapping ou integration quando aplicável.
+- [ ] Evitei recriar CRUD.
+- [ ] Validei entrada.
+- [ ] Validei permissão no backend.
+- [ ] Tratei erros.
+- [ ] Não hardcodei segredos.
+- [ ] Mantive rastreabilidade.
+
+## Frontend
+
+- [ ] Usei `central.ui.json` antes de criar componente customizado.
+- [ ] Evitei recriar shell, rotas, menu, datagrid ou form.
+- [ ] Usei override apenas quando necessário.
+- [ ] Não coloquei regra crítica apenas no frontend.
+
+## Integrações
+
+- [ ] Usei camada de integração/conector.
+- [ ] Modelei mapping.
+- [ ] Registrei status de integração.
+- [ ] Normalizei erros externos.
+- [ ] Não expus credenciais.
+
+## Entrega
+
+- [ ] A Central continua atualizável com novas versões do Core.
+- [ ] A alteração é pequena, coesa e aderente à arquitetura.
+- [ ] O comportamento esperado está documentado no README ou no próprio módulo quando necessário.

package/docs/CODEX.md

@@ -0,0 +1,46 @@
+# CODEX.md — Regras de Codificação OonCore
+
+Este arquivo é a porta de entrada para o Codex codificar uma Central Oon.
+
+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`.
+
+## Antes de codificar
+
+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.
+
+## Princípios obrigatórios
+
+- Escreva apenas o domínio da Central.
+- 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 models, validations, triggers, hooks, mappings, documents, pipelines, integrations e overrides declarativos.
+
+## Ordem de decisão
+
+Ao implementar uma necessidade, siga esta ordem:
+
+1. Configuração existente do Core.
+2. Declaração em `central.config.js` ou `central.ui.json`.
+3. Model, validation, trigger, hook ou mapping no backend da Central.
+4. Override local pequeno e isolado.
+5. 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/*`.

package/docs/COLLECTIONS_AND_PIPELINES.md

@@ -0,0 +1,66 @@
+# Coleções, Documentos e Esteiras
+
+Coleções, documentos e esteiras são a base operacional da Central Oon.
+
+## Coleções
+
+Use coleções para entidades de negócio:
+
+- clientes;
+- fornecedores;
+- pedidos;
+- pagamentos;
+- documentos fiscais;
+- serviços tomados;
+- serviços prestados;
+- integrações;
+- tickets operacionais.
+
+Cada coleção deve ter:
+
+- model no backend;
+- metadata para CRUD;
+- campos de status quando participar de esteira;
+- validações de negócio;
+- configuração de tela no frontend.
+
+## Documentos
+
+Use documentos para entidades que exigem governança documental, aprovação, anexos ou histórico específico.
+
+Exemplos:
+
+- NF;
+- contrato;
+- proposta;
+- comprovante;
+- ordem de serviço;
+- pedido de compra.
+
+## Esteiras de processo
+
+Use esteiras para fluxos operacionais com etapas claras.
+
+Boas práticas:
+
+- status/etapa deve estar no backend;
+- transições devem ser validadas;
+- ações devem registrar usuário e data;
+- exceções devem ter status próprio;
+- cada etapa deve representar uma decisão operacional real.
+
+## Esteiras de integração
+
+Use esteiras de integração para acompanhar comunicação com sistemas externos.
+
+Estados recomendados:
+
+- pendente;
+- em processamento;
+- enviado;
+- concluído;
+- falha;
+- aguardando retry;
+- cancelado.
+
+Integrações não devem ser caixas-pretas. O usuário operacional precisa enxergar o que aconteceu, qual erro ocorreu e qual ação pode ser tomada.

package/docs/CONNECTORS_AND_INTEGRATIONS.md

@@ -0,0 +1,66 @@
+# Conectores e Integrações
+
+Toda integração deve ser modelada como um processo rastreável, não como chamada solta dentro de controller.
+
+## Objetivo
+
+Transformar cada integração em:
+
+```txt
+configuração + mapping + execução + status + rastreabilidade
+```
+
+## Estrutura recomendada
+
+```txt
+backend/src/integrations/
+├── <sistema>/
+│   ├── client.js
+│   ├── mappings/
+│   ├── services/
+│   └── README.md
+```
+
+## Client
+
+O client deve concentrar:
+
+- URL base;
+- autenticação;
+- headers;
+- timeout;
+- retry técnico;
+- normalização de erro.
+
+Não coloque regra de negócio no client.
+
+## Mapping
+
+Mappings devem transformar dados entre a Central e o sistema externo.
+
+Regras:
+
+- mapping deve ser explícito;
+- campos obrigatórios devem ser validados antes do envio;
+- resposta externa deve ser normalizada;
+- erros devem ser compreensíveis para operação.
+
+## Esteira de integração
+
+Toda integração relevante deve gerar registro operacional com:
+
+- origem;
+- destino;
+- payload resumido ou referência;
+- status;
+- tentativas;
+- erro normalizado;
+- data/hora;
+- usuário ou processo responsável.
+
+## Segurança
+
+- Nunca versionar app key, secret, token ou credencial.
+- Não logar payloads sensíveis sem necessidade.
+- Não expor credenciais no frontend.
+- Usar `.env` e configuração de ambiente.

package/docs/DO_AND_DONT.md

@@ -0,0 +1,27 @@
+# Do and Don't
+
+## Faça
+
+- Use o Core antes de criar código novo.
+- Modele o domínio com clareza.
+- Prefira configuração e metadata.
+- Escreva validações explícitas.
+- Mantenha regras críticas no backend.
+- Use esteiras para processos com status.
+- Use conectores para integrações.
+- Registre erros de forma operacional.
+- Mantenha compatibilidade com atualização dos pacotes.
+- Atualize `.ooncore/` com `npm run ooncore:docs`.
+
+## Não faça
+
+- Não recrie CRUD.
+- Não recrie autenticação.
+- Não duplique RBAC no frontend.
+- Não criar um frontend inteiro se um override resolve.
+- Não chamar APIs externas direto de qualquer lugar.
+- Não hardcode tenant, app, usuário, URL sensível ou segredo.
+- Não colocar regra crítica apenas no frontend.
+- Não ignorar logs e rastreabilidade.
+- Não editar `.ooncore/context.generated.md` manualmente.
+- Não depender de documentação externa para codificar a arquitetura.

package/docs/FRONTEND_PATTERNS.md

@@ -0,0 +1,66 @@
+# Padrões Frontend
+
+O frontend da Central deve ser declarativo. Shell, providers, rotas, menu, datagrid, formulários, documentos e esteiras pertencem ao `@oondemand/oon-core-front`.
+
+## Estrutura esperada
+
+```txt
+frontend/
+├── central.ui.json
+└── src/
+    ├── main.tsx
+    ├── collections/
+    ├── documents/
+    ├── pipelines/
+    ├── dashboards/
+    └── overrides/
+```
+
+## central.ui.json
+
+Use `central.ui.json` como entrada principal para declarar:
+
+- menu;
+- coleções;
+- campos exibidos;
+- filtros;
+- ações;
+- formulários;
+- documentos;
+- esteiras;
+- dashboards;
+- agrupamentos.
+
+## Regras
+
+- Não recrie layout completo se o Core já renderiza.
+- Não duplique chamada REST manual se o SDK do Core já atende.
+- Não coloque regra de permissão apenas no frontend.
+- Não hardcode endpoints quando a metadata puder fornecer.
+- Não crie variações visuais fora do padrão sem necessidade real.
+- Use overrides pequenos, específicos e documentados.
+
+## Overrides
+
+Overrides são permitidos para:
+
+- campo especial;
+- ação específica;
+- card customizado;
+- cabeçalho customizado;
+- dashboard customizado;
+- integração visual pontual.
+
+Overrides não devem virar uma reimplementação do Core.
+
+## Experiência padrão
+
+A Central deve manter o padrão OonCore:
+
+- navegação consistente;
+- datagrids densos;
+- formulários claros;
+- feedback visual;
+- status por badges;
+- ações rastreáveis;
+- responsividade.

package/docs/OONCORE_ARCHITECTURE.md

@@ -0,0 +1,50 @@
+# Arquitetura OonCore
+
+O OonCore é a base para criar Centrais operacionais sob demanda com arquitetura padronizada, segura e evolutiva.
+
+A Central gerada não deve nascer como um sistema completo do zero. Ela deve nascer como uma camada de domínio que consome os recursos do Core.
+
+## Separação de responsabilidades
+
+```txt
+Central
+├── backend/   domínio, regras, validações, integrações e esteiras
+└── frontend/  declaração de telas, coleções, documentos e overrides
+
+OonCore Back
+├── boot Express
+├── Mongo/Mongoose
+├── autenticação
+├── RBAC
+├── CRUD metadata-driven
+├── auditoria
+├── triggers/hooks
+└── APIs padrão
+
+OonCore Front
+├── shell React
+├── providers
+├── roteamento
+├── menu
+├── datagrid
+├── formulários
+├── documentos
+├── esteiras
+└── SDK REST
+```
+
+## Modelo mini-monolítico
+
+Cada Central começa como um mini-monolito de negócio: pequeno, coeso, isolado e capaz de entregar valor rapidamente. Quando uma parte do domínio se tornar reutilizável, crítica ou independente, ela pode evoluir para conector, serviço compartilhado ou micro-serviço.
+
+## Fonte de verdade
+
+- Dados e regras ficam no backend.
+- Metadata operacional é exposta pelo backend.
+- Frontend renderiza a experiência a partir da metadata.
+- Permissões são decididas no backend.
+- Integrações são tratadas como conectores, mappings, triggers e esteiras de integração.
+
+## Objetivo do Codex
+
+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.

package/docs/RBAC_SECURITY.md

@@ -0,0 +1,35 @@
+# RBAC e Segurança
+
+A segurança da Central deve ser aplicada no backend. O frontend pode ocultar ou exibir ações, mas não é a fonte de decisão.
+
+## Regras obrigatórias
+
+- Toda operação sensível deve validar usuário autenticado.
+- Toda alteração de dados deve validar permissão.
+- Toda ação de integração deve validar permissão e contexto.
+- Nunca confiar em `tenantId`, `appId`, `perfil` ou `roles` enviados livremente pelo frontend.
+- Segredos devem vir de variáveis de ambiente ou vault equivalente.
+- Logs não devem expor tokens, senhas, app keys ou dados sensíveis desnecessários.
+
+## RBAC
+
+Use o RBAC do Core para:
+
+- controlar acesso por app;
+- controlar perfis;
+- controlar ações;
+- filtrar funcionalidades;
+- proteger rotas;
+- permitir evolução de permissões sem reconstruir telas.
+
+## Checklist de segurança para Codex
+
+Antes de concluir uma alteração, confirme:
+
+- Existe validação de entrada?
+- Existe validação de permissão no backend?
+- Existe tratamento de erro?
+- A operação gera rastreabilidade?
+- Algum segredo foi colocado no código?
+- Algum dado sensível foi exposto no frontend?
+- O comportamento funciona para múltiplos usuários e múltiplos apps?

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@oondemand/create-central-oon",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oondemand/oon-platform.git",
     "directory": "packages/create-central-oon"
   },
-  "description": "Gerador de Centrais Oon com backend declarativo e frontend padrão Central Minexco: menu, datagrids, formulários e esteiras.",
+  "description": "Gerador de Centrais Oon com backend declarativo, frontend padrão e documentação interna OonCore para Codex.",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js"
@@ -19,6 +19,7 @@
     "bin",
     "src",
     "templates",
+    "docs",
     "README.md"
   ],
   "engines": {
@@ -30,7 +31,9 @@
     "central",
     "scaffold",
     "create",
-    "generator"
+    "generator",
+    "codex",
+    "docs"
   ],
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": {

package/src/index.js

@@ -2,10 +2,13 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
+const crypto = require("node:crypto");
 const { spawnSync } = require("node:child_process");
 const { copyTemplate } = require("./render");
 
-const TEMPLATES_DIR = path.join(__dirname, "..", "templates");
+const PACKAGE_ROOT = path.join(__dirname, "..");
+const TEMPLATES_DIR = path.join(PACKAGE_ROOT, "templates");
+const DOCS_DIR = path.join(PACKAGE_ROOT, "docs");
 
 const TEMPLATES = [
   { id: "basic", description: "Central mínima com uma coleção dinâmica (Pessoa)." },
@@ -52,6 +55,183 @@ function npmInstall(dir) {
   return !r.status && !r.error;
 }
 
+function readPackageVersion() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8"));
+  return pkg.version;
+}
+
+function listDocFiles(dir = DOCS_DIR, prefix = "") {
+  if (!fs.existsSync(dir)) return [];
+  const files = [];
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const relative = path.join(prefix, entry.name);
+    const absolute = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...listDocFiles(absolute, relative));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      files.push(relative);
+    }
+  }
+
+  return files.sort((a, b) => a.localeCompare(b));
+}
+
+function docsHash(files = listDocFiles()) {
+  const hash = crypto.createHash("sha256");
+  for (const file of files) {
+    const normalized = file.split(path.sep).join("/");
+    hash.update(normalized);
+    hash.update("\n");
+    hash.update(fs.readFileSync(path.join(DOCS_DIR, file)));
+    hash.update("\n");
+  }
+  return hash.digest("hex");
+}
+
+function resolveCentralRoot(cwd = process.cwd()) {
+  const current = path.resolve(cwd);
+  const parent = path.dirname(current);
+
+  if (fs.existsSync(path.join(current, "backend")) && fs.existsSync(path.join(current, "frontend"))) {
+    return current;
+  }
+
+  if (
+    ["backend", "frontend"].includes(path.basename(current)) &&
+    fs.existsSync(path.join(parent, "backend")) &&
+    fs.existsSync(path.join(parent, "frontend"))
+  ) {
+    return parent;
+  }
+
+  return current;
+}
+
+function removeDir(dir) {
+  if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
+}
+
+function copyDocs(srcDir, destDir) {
+  if (!fs.existsSync(srcDir)) {
+    throw new Error(`Diretório de documentação não encontrado: ${srcDir}`);
+  }
+
+  fs.mkdirSync(destDir, { recursive: true });
+
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const from = path.join(srcDir, entry.name);
+    const to = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDocs(from, to);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(from, to);
+    }
+  }
+}
+
+function buildContext(files = listDocFiles()) {
+  const header = [
+    "# OonCore Contexto Consolidado para Codex",
+    "",
+    "> 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.",
+    "",
+  ].join("\n");
+
+  const sections = files
+    .map((file) => {
+      const normalized = file.split(path.sep).join("/");
+      const content = fs.readFileSync(path.join(DOCS_DIR, file), "utf8").trim();
+      return [
+        "---",
+        "",
+        `<!-- source: ${normalized} -->`,
+        "",
+        content,
+        "",
+      ].join("\n");
+    })
+    .join("\n");
+
+  return `${header}\n${sections}`;
+}
+
+function buildManifest(files = listDocFiles()) {
+  return {
+    source: "@oondemand/create-central-oon",
+    version: readPackageVersion(),
+    generatedAt: new Date().toISOString(),
+    docsMode: "generated-cache",
+    docsHash: docsHash(files),
+    files: files.map((file) => file.split(path.sep).join("/")),
+  };
+}
+
+function syncDocs(opts = {}) {
+  const root = resolveCentralRoot(opts.cwd);
+  const outDir = path.join(root, ".ooncore");
+  const docsOutDir = path.join(outDir, "docs");
+  const files = listDocFiles();
+
+  if (!files.length) {
+    throw new Error("Nenhum arquivo .md encontrado em packages/create-central-oon/docs.");
+  }
+
+  fs.mkdirSync(outDir, { recursive: true });
+  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"));
+  }
+
+  fs.writeFileSync(path.join(outDir, "context.generated.md"), buildContext(files));
+  fs.writeFileSync(path.join(outDir, "manifest.json"), `${JSON.stringify(buildManifest(files), null, 2)}\n`);
+
+  console.log(`✔ Documentação OonCore sincronizada em ${path.relative(process.cwd(), outDir) || ".ooncore"}`);
+  console.log(`  Versão: ${readPackageVersion()}`);
+  console.log(`  Arquivos: ${files.length}`);
+}
+
+function checkDocs(opts = {}) {
+  const root = resolveCentralRoot(opts.cwd);
+  const manifestPath = path.join(root, ".ooncore", "manifest.json");
+  const version = readPackageVersion();
+  const files = listDocFiles();
+  const currentHash = docsHash(files);
+
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error("Documentação OonCore local não encontrada. Rode `npm run ooncore:docs`.");
+  }
+
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  const problems = [];
+
+  if (manifest.source !== "@oondemand/create-central-oon") {
+    problems.push(`fonte esperada @oondemand/create-central-oon, encontrada ${manifest.source || "(vazia)"}`);
+  }
+
+  if (manifest.version !== version) {
+    problems.push(`versão local ${manifest.version || "(vazia)"} diferente da instalada ${version}`);
+  }
+
+  if (manifest.docsHash !== currentHash) {
+    problems.push("hash da documentação local diferente da documentação instalada");
+  }
+
+  if (problems.length) {
+    throw new Error(`Documentação OonCore desatualizada:\n- ${problems.join("\n- ")}\nRode \`npm run ooncore:docs\`.`);
+  }
+
+  console.log(`✔ Documentação OonCore atualizada (versão ${version}).`);
+}
+
 async function run(opts) {
   const template = TEMPLATES.find((t) => t.id === opts.template);
   if (!template) {
@@ -81,13 +261,19 @@ 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.
+  syncDocs({ cwd: targetDir });
+
   console.log("✔ Arquivos gerados.");
 
   if (opts.install) {
     console.log("\n📦 Instalando dependências (best-effort)...");
+    const rootOk = fs.existsSync(path.join(targetDir, "package.json"))
+      ? npmInstall(targetDir)
+      : true;
     const backOk = npmInstall(path.join(targetDir, "backend"));
     const frontOk = npmInstall(path.join(targetDir, "frontend"));
-    if (!backOk || !frontOk) {
+    if (!rootOk || !backOk || !frontOk) {
       console.warn(
         "\n⚠ npm install falhou em um dos projetos (esperado se os pacotes @oondemand/* ainda não foram publicados). Rode manualmente depois."
       );
@@ -103,7 +289,11 @@ function printNextSteps(tokens, opts) {
 ✅ Central "${tokens.name}" pronta.
 
 Próximos passos:
-${cd}  # Backend (só domínio — models/validations/triggers/...)
+${cd}  # Sincronizar/validar documentação local do Core para Codex
+  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)
@@ -114,4 +304,13 @@ Edite backend/src/models e frontend/central.ui.json para evoluir a Central.
 `);
 }
 
-module.exports = { run, listTemplates, toSlug, toPascal, toTitle };
+module.exports = {
+  run,
+  listTemplates,
+  toSlug,
+  toPascal,
+  toTitle,
+  syncDocs,
+  checkDocs,
+  resolveCentralRoot,
+};

package/templates/_base/README.md

@@ -1,7 +1,6 @@
 # __NAME__
 
-Central Oon gerada com `create-central-oon`. É composta por dois projetos
-mínimos que consomem o Core:
+Central Oon gerada com `create-central-oon`. É composta por dois projetos mínimos que consomem o Core:
 
 - **backend/** — só domínio (`src/models`, `validations`, `triggers`, …).
   Sobe com `oonCore-back dev`. Toda a infra (boot, db, auth, RBAC, metadata,
@@ -10,9 +9,26 @@ mínimos que consomem o Core:
   dev`. Shell, providers, roteamento, auth e telas vêm do
   `@oondemand/oon-core-front`, renderizados a partir do `/core/metadata` do back.
 
+## Documentação local do OonCore
+
+A pasta `.ooncore/` é gerada automaticamente a partir da versão instalada do pacote `@oondemand/create-central-oon`.
+
+Ela serve como contexto local para o Codex codificar sem depender de site externo.
+
+```bash
+npm run ooncore:docs        # sincroniza .ooncore/
+npm run ooncore:docs:check  # valida versão/hash da documentação local
+```
+
+Não edite `.ooncore/context.generated.md` manualmente. Atualize o pacote e rode o sync.
+
 ## Rodando
 
 ```bash
+# raiz da Central
+npm install
+npm run ooncore:docs:check
+
 # backend
 cd backend && cp .env.example .env && npm install && npm run dev
 
@@ -24,4 +40,5 @@ cd frontend && cp .env.example .env && npm install && npm run dev
 
 1. Crie models em `backend/src/models` (só schema + CRUD).
 2. Declare as telas em `frontend/central.ui.json` (coleções/esteiras/documentos).
-3. O resto — grid, form, rotas, menu — é montado pelo Core automaticamente.
+3. Use validations, triggers, hooks, mappings e integrations para regras e processos.
+4. O resto — grid, form, rotas, menu — é montado pelo Core automaticamente.

package/templates/_base/backend/package.json

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

package/templates/_base/frontend/package.json

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

package/templates/_base/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "__SLUG__",
+  "version": "0.1.0",
+  "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",
+    "dev:backend": "npm run dev --prefix backend",
+    "dev:frontend": "npm run dev --prefix frontend"
+  },
+  "devDependencies": {
+    "@oondemand/create-central-oon": "^0.3.8"
+  }
+}