mxrb 0.1.0

data/docs/pt-BR/architecture.md

@@ -0,0 +1,300 @@
+# Arquitetura de projetos Mendix no mxrb
+
+**Português** · [English](../en-US/architecture.md) · [Deutsch](../de-DE/architecture.md)
+
+Este documento define a estrutura canônica de um projeto editável pelo `mxrb`.
+Ela tem dois objetivos igualmente importantes:
+
+1. permitir escrever o projeto em Ruby e gerar um `.mpr`;
+2. exportar um `.mpr` existente para Ruby, editar e gerar Mendix novamente.
+
+O Ruby é uma representação versionável do metamodelo Mendix. Ele não é uma
+segunda aplicação executada em paralelo ao runtime Mendix.
+
+As regras normativas de classificação de microflows, nanoflows, security,
+navigation e design system estão em
+[padrão arquitetural](architectural-standard.md).
+
+## Princípios de compatibilidade com Mendix
+
+Um app Mendix é uma árvore de **units**. O app é a raiz; módulos e pastas são
+units estruturais; Domain Models, páginas e microflows são units de modelo.
+Cada módulo possui exatamente um Domain Model, além de seus documentos e
+configurações.
+
+Por isso, a principal fronteira arquitetural do `mxrb` também é o **módulo**.
+Um módulo deve representar uma capacidade de negócio ou integração substituível,
+por exemplo `CustomerManagement`, `OrderManagement` ou `PaymentIntegration`.
+
+Referências:
+
+- [App Explorer](https://docs.mendix.com/refguide/app-explorer/)
+- [Modules](https://docs.mendix.com/refguide/modules/)
+- [Mendix Metamodel](https://docs.mendix.com/apidocs-mxsdk/mxsdk/mendix-metamodel/)
+- [Naming Convention Best Practices](https://docs.mendix.com/refguide/naming-convention-best-practices/)
+
+## Estrutura canônica
+
+```text
+meu_app/
+├── project.rb
+├── modules/
+│   ├── CustomerManagement/
+│   │   ├── module.rb
+│   │   ├── domain/
+│   │   │   ├── model.rb
+│   │   │   └── entities/
+│   │   │       ├── customer.rb
+│   │   │       └── order.rb
+│   │   ├── application/
+│   │   │   ├── application.rb
+│   │   │   └── microflows/
+│   │   │       └── create_order.rb
+│   │   ├── presentation/
+│   │   │   ├── presentation.rb
+│   │   │   └── pages/
+│   │   │       └── order_list.rb
+│   │   └── infrastructure/
+│   │       └── .keep
+│   └── OrderManagement/
+│       └── ...
+├── resources/                 # arquivos externos ao metamodelo, quando houver
+├── themesource/               # estrutura nativa do tema Mendix
+├── widgets/                   # widgets pluggable nativos
+└── vendor/                    # módulos/artefatos externos, não editados pelo domínio
+```
+
+Arquivos como `themesource/`, `widgets/`, `javasource/`, `deployment/` e
+`resources/` devem manter os nomes e formatos esperados pelo Mendix. O `mxrb`
+não deve esconder ou renomear esses diretórios.
+
+## Mapeamento para Clean Architecture
+
+### `domain/`
+
+Contém o Domain Model do módulo:
+
+- entidades;
+- atributos;
+- associações;
+- enumerações;
+- regras de domínio puras, quando suportadas.
+
+O domínio não deve depender de páginas, serviços externos ou detalhes de
+infraestrutura. Uma entidade deve ter nome singular em PascalCase, como
+`Customer` ou `PurchaseOrder`.
+
+`domain/` representa o único Domain Model permitido pelo módulo Mendix.
+`domain/model.rb` é somente o agregador; cada entidade fica em seu próprio
+arquivo dentro de `domain/entities/`. Associações ficam no arquivo da entidade
+que possui a referência.
+
+```ruby
+# domain/model.rb
+evaluate File.join(__dir__, "entities", "customer.rb")
+evaluate File.join(__dir__, "entities", "order.rb")
+```
+
+```ruby
+# domain/entities/order.rb
+entity :Order do
+  decimal :Total, default: 0
+  association "Sales.Customer", name: "Order_Customer"
+end
+```
+
+A cardinalidade segue o modelo de tipo/proprietário do Mendix:
+
+```ruby
+# 1:N (padrão): Reference + Default
+association "Sales.Customer", name: "Order_Customer"
+
+# 1:1: Reference + Both
+association "Sales.Profile", name: "Customer_Profile", owner: :Both
+
+# N:N: ReferenceSet + Default
+association "Sales.Tag", name: "Order_Tags", type: :ReferenceSet
+```
+
+### `application/`
+
+Contém casos de uso e coordenação:
+
+- microflows;
+- nanoflows;
+- regras de aplicação;
+- scheduled events;
+- task queues.
+
+Convenções úteis para microflows:
+
+- `ACT_`: operação de negócio reutilizável;
+- `VAL_`: validação;
+- `DS_`: data source;
+- `SUB_`: submicroflow interno;
+- `IVK_`: ação invocada pela interface;
+- `API_`: operação exposta como contrato.
+
+Esses prefixos são uma convenção do projeto, não uma exigência do formato MPR.
+
+Cada microflow fica em `application/microflows/<nome>.rb`.
+`application/application.rb` é somente o agregador desses arquivos.
+
+### `presentation/`
+
+Contém a interface:
+
+- páginas;
+- layouts;
+- snippets;
+- menus;
+- recursos de navegação específicos do módulo.
+
+A apresentação pode chamar casos de uso em `application/`, mas não deve
+implementar regras centrais de negócio.
+
+Cada página fica em `presentation/pages/<nome>.rb`.
+`presentation/presentation.rb` é somente o agregador.
+
+### `infrastructure/`
+
+Contém adaptadores e detalhes externos:
+
+- consumed/published REST, OData, GraphQL e SOAP;
+- import/export mappings;
+- message definitions;
+- Java e JavaScript actions;
+- persistência ou conectores externos;
+- constantes técnicas.
+
+Microflows de infraestrutura devem ser chamados pela camada de aplicação. O
+domínio não deve depender diretamente deles.
+
+## Regra de dependências
+
+```text
+presentation ──────┐
+                   ├──> application ───> domain
+infrastructure ────┘
+```
+
+- `domain` não conhece nenhuma outra camada.
+- `application` conhece o domínio e contratos necessários.
+- `presentation` chama a aplicação.
+- `infrastructure` implementa integrações usadas pela aplicação.
+- dependências entre módulos devem passar por operações públicas documentadas,
+  evitando acesso disperso aos detalhes internos de outro módulo.
+
+O Mendix não aplica essas restrições automaticamente; o `mxrb lint` deverá
+validá-las em uma etapa futura.
+
+## Arquivo raiz
+
+`project.rb` monta o app e pode ser executado diretamente pelo comando
+`mxrb generate`:
+
+```ruby
+require "mxrb"
+
+output = ENV.fetch("MXRB_OUTPUT_PATH", File.join(__dir__, "MyApp.mpr"))
+
+Mxrb.define(output) do
+  mendix_version "10.17.0"
+  evaluate File.join(__dir__, "modules", "CustomerManagement", "module.rb")
+  evaluate File.join(__dir__, "modules", "OrderManagement", "module.rb")
+end
+```
+
+Cada `module.rb` abre uma única definição de módulo:
+
+```ruby
+self.module :OrderManagement do
+  evaluate File.join(__dir__, "domain", "model.rb")
+  evaluate File.join(__dir__, "application", "application.rb")
+  evaluate File.join(__dir__, "presentation", "presentation.rb")
+end
+```
+
+## Fluxo Ruby para Mendix
+
+```sh
+bundle exec mxrb generate meu_app/project.rb build/MyApp.mpr
+```
+
+O writer usa nomes como chave estável ao atualizar módulos, entidades,
+atributos, associações e documentos. Reaplicar a mesma fonte Ruby não deve
+duplicar artefatos.
+
+Para projetos reais, mantenha o `.mpr` e o diretório `mprcontents/` juntos. Em
+MPR v2, ambos formam o projeto.
+
+## Fluxo Mendix para Ruby
+
+```sh
+bundle exec mxrb export MyApp.mpr meu_app/
+```
+
+O exportador cria:
+
+- `project.rb`;
+- um diretório por módulo;
+- `domain/model.rb` como agregador;
+- `domain/entities/*.rb`, um arquivo por entidade;
+- `application/application.rb` e um arquivo por microflow;
+- `presentation/presentation.rb` e um arquivo por página;
+- o espaço reservado de `infrastructure/`.
+
+Depois da exportação:
+
+```sh
+bundle exec mxrb generate meu_app/project.rb build/MyApp.mpr
+```
+
+Esse round-trip preserva o metamodelo conhecido pelo `mxrb`. Flows dos fixtures
+públicos são DSL tipada; páginas/widgets avançados usam um hash Ruby profundo e
+editável. Units fora dessas superfícies usam o manifesto nativo como baseline
+lossless até ganharem uma representação Ruby própria.
+
+## Estratégia segura de round-trip
+
+Há dois modos de trabalho:
+
+### Atualização preservadora
+
+Exporte um MPR, edite o Ruby e gere sobre uma cópia do MPR original. Esse é o
+modo recomendado porque units ainda desconhecidas pelo `mxrb` continuam no
+arquivo.
+
+```sh
+cp MyApp.mpr work/MyApp.mpr
+cp -R mprcontents work/mprcontents   # somente para MPR v2
+bundle exec mxrb generate meu_app/project.rb work/MyApp.mpr
+```
+
+### Reconstrução
+
+Gere um MPR novo a partir do Ruby. Use apenas quando todos os artefatos
+necessários estiverem representados pelo DSL. Neste estágio, configurações
+globais, segurança completa, widgets complexos, integrações e alguns tipos de
+documento ainda não são reconstruídos integralmente.
+
+## Convenções de nomes
+
+- módulos: `UpperCamelCase`, descrevendo responsabilidade;
+- entidades: singular e `PascalCase`;
+- atributos: `PascalCase`;
+- detalhes técnicos de entidade: prefixo `_`;
+- associações: padrão Mendix `Origem_Destino`;
+- nomes públicos devem ser estáveis, pois o Mendix usa nomes para reconciliar
+  vários artefatos durante substituições e atualizações.
+
+## Fonte de verdade
+
+Escolha uma fonte de verdade por branch de trabalho:
+
+- **Ruby-first**: Ruby é editado; o MPR é artefato gerado/atualizado.
+- **Mendix-first**: Studio Pro é editado; execute `mxrb export` antes de alterar
+  o Ruby.
+
+Não edite simultaneamente os mesmos artefatos nos dois lados. O fluxo futuro de
+`mxrb diff` deverá detectar divergências antes da conversão.

data/docs/pt-BR/compiler.md

@@ -0,0 +1,162 @@
+# Compilador nativo, Runtime e formato MDA
+
+O pipeline funcional do MXRB não executa `mx`, `mxbuild`, `mxcli`, Studio Pro
+ou Model SDK. Esses programas podem continuar sendo usados como gates externos
+de compatibilidade, mas não são dependências do build, do banco ou dos testes
+funcionais.
+
+## Build do zero
+
+`DeploymentMaterializer` cria um `deployment/` inexistente a partir dos
+templates da versão instalada e executa 12 estágios: segurança, constantes,
+domain model, artefatos, traduções, textos de sistema, filas de sistema, modelo
+cliente, actions, settings, microflows e índice de projeto/módulos. Ele também
+gera `metadata.json`, dependências e o `model.mdp` em ordem BSON aceita pelo
+Runtime.
+
+O bootstrap possui seeds e catálogos auditados para 6.10.8, 7.5.0, 7.17.0,
+9.6.1.29396, 10.24.0.73019 e 11.12.1. As famílias 6.x, 7.x, 9.x, 10.x e 11.x selecionam o seed
+compatível; 5.x e 8.x falham fechadas por ainda não terem seed auditado.
+Esse agrupamento vale para o schema do compilador. A Runtime deve sempre ter o
+mesmo patch exato do MPR.
+
+`ProjectJarBuilder` encontra o JDK por `MXRB_JAVA_HOME`, `JAVA_HOME`, asdf ou
+mise, compila `javasource/**/*.java` com as bibliotecas do Runtime e do projeto
+e escreve um `project.jar` OSGi determinístico. No VetClinic foram compilados
+183 fontes em 249 classes.
+
+`WebBundleBuilder` seleciona Dojo em 6/7, Dojo com React wrapper em 9, o cliente
+clássico ou otimizado declarado pelo projeto em 10 e React em 11. No React,
+gera entrypoint e módulos, expande `.mpk` e chama diretamente o Node/Rollup
+da versão 10 ou Node/Rspack da versão 11. O Data Grid 2 é compilado no subconjunto com
+fonte XPath e colunas de atributo, incluindo `operations.json`, datasource e
+tipos dos atributos. Tipos ou combinações ainda não traduzidos recebem um
+fallback DOM e ficam registrados em `web/mxrb-pages.json`; o manifesto do
+VetClinic ficou vazio.
+
+O compilador React também materializa containers, textos e títulos, grids
+responsivos, colunas e botões de abertura/criação. O bootstrap injeta
+`theme.compiled.css`, manifest e assets `themesource/*/public`; portanto uma
+homepage com `LayoutGrid` não fica vazia. Para adicionar conteúdo em Ruby:
+
+Formulários `DataView` ligados a parâmetros agora renderizam campos `TextBox`
+editáveis e ações Save/Cancel. Create passa o GUID do novo objeto por
+`openForm2`; as operações commit/rollback são registradas com os user roles do
+projeto derivados dos module roles permitidos pela página. A autorização da
+Runtime é preservada, sem contorno de segurança.
+
+Layouts, placeholders, regiões de scroll, sidebars, headers, menus de navegação,
+snippets, DataViews, ListViews, controles de formulário, imagens, combo boxes,
+Gallery, Data Grid 2 e widgets pluggable respaldados por schema são compilados
+pelos contratos nativos do cliente React. Ações de páginas, menus e widgets
+cobrem navegação, microflows, nanoflows, ciclo de vida de objetos, links e
+sign-out. Programas nanoflow também cobrem decisões, error handlers,
+ações JavaScript e operações server-side de microflow/commit quando o contrato
+do modelo pode ser mapeado com segurança.
+
+O caminho React também compila a Gallery oficial com listas XPath e microflow,
+conteúdo de item por template, seleção e atributos dinâmicos formatados. Fontes
+e ações nanoflow usam os contratos `NanoflowObjectListProperty`,
+`NanoflowObjectProperty` e `ActionProperty` do cliente Mendix. O MXRB emite
+programas cliente reais `{ name, instructions }` para controle de fluxo em
+grafo, retornos, variáveis, objetos, chamadas de nanoflow/microflow, ações
+JavaScript, páginas, mensagens, validações e commits. Fluxos ausentes,
+mapeamentos de parâmetro inseguros e instruções cliente não traduzidas falham
+fechado e permanecem achados no manifesto de suporte.
+
+Nas sessões locais da Runtime em modo developer, o mxrb também versiona imports
+dinâmicos de páginas, aplica hash de conteúdo ao chunk corrigido do React Client
+e dá à autoimportação do Rspack o mesmo token do entrypoint. Isso impede que as
+respostas estáticas de longa duração do Mendix restaurem uma página branca
+obsoleta depois de um rebuild nativo. O shell gerado também fornece um adaptador
+limitado de `openForm` sobre `openForm2`; assim, handlers antigos em cache
+navegam em vez de terminar silenciosamente sem disparar request.
+
+```ruby
+Mxrb.define("App.mpr") do
+  mendix_version "11.12.1"
+  self.module(:App) do
+    layout :Shell
+    page(:Home) do
+      layout "App.Shell"
+      title "Minha aplicação"
+      container(:main, class_name: "container") do
+        text :welcome, caption: "Conteúdo criado com mxrb"
+      end
+    end
+  end
+end
+```
+
+Projetos existentes podem ser exportados, alterados na DSL e regenerados. Os
+widgets fora do subconjunto continuam no manifesto, sem descarte silencioso.
+
+Antes do build nativo, audite o MPR completo pelo renderer selecionado para sua
+versão Mendix:
+
+```bash
+mxrb preflight App.mpr
+mxrb preflight App.mpr --json
+```
+
+O comando é somente leitura e retorna código diferente de zero para versões ou
+recursos cliente não suportados. Mendix 11 é auditado pelo compilador React;
+6/7/9 usam a mesma auditoria Dojo legada do `WebBundleBuilder`. Assim o relatório
+não declara compatibilidade por um renderer que o build real não utilizará.
+
+No Dojo, o Data Grid 1 cobre fontes database, XPath e microflow, pesquisa,
+ordenação, paginação, seleção e botões auditados. Outros widgets visuais são
+registrados por página em `web/mxrb-legacy-pages.json`; não são declarados como
+renderizados. Esse manifesto evita que XML servido seja confundido com página
+visualmente completa.
+
+## MDA e pacote portátil
+
+```bash
+mxrb pack Clinic.mpr --output build/Clinic.mda
+mxrb mda inspect build/Clinic.mda
+mxrb portable Clinic.mpr --output build/runtime.zip
+```
+
+O MDA e o ZIP portátil são determinísticos. O pacote portátil combina o
+deployment nativo com o Runtime instalado da mesma versão, configurações,
+constantes e scripts. Somente as raízes oficiais entram no MDA; diretórios de
+trabalho como `data`, `log`, `run`, `build` e `.gradle` são excluídos.
+
+## Evidência de regressão
+
+```bash
+script/runtime_boot_regression App.mpr /caminho/inexistente/deployment \
+  ~/.local/share/mendix/11.12.1
+```
+
+O teste trabalha em diretório temporário, cria o deployment, compila Java e
+web, empacota, inicia o Runtime e exige HTTP 200 para `/`, `dist/index.js` e
+cada bundle de página. Também verifica shutdown limpo. O transcript e o SHA-256
+ficam em `tmp/runtime-boot-evidence.log`. Quando Chromium está instalado, o
+teste importa todos os módulos e instancia os factories que não exigem sessão.
+O bundle do Data Grid é importado e avaliado; seu factory consulta a sessão do
+cliente e, por isso, exige um teste autenticado para ser instanciado.
+
+Em 1º de agosto de 2026, o VetClinic 11.12.1 partiu de deployment inexistente,
+executou 675 comandos de sincronização de banco, ativou as filas `System`,
+agendou `VetClinic.Cleanup`, respondeu 200 nos quatro bundles de página e
+encerrou limpo. O teste funcional `ACT Create Animal` passou em seguida.
+
+## Limites explícitos
+
+- os 12 estágios e a geração web limpa foram validados em 6.10.8, 7.5.0,
+  7.17.0, 9.6.1.29396, 10.24.0.73019 e 11.12.1;
+- o boot nativo exato foi provado em 10.24.0.73019 e 11.12.1. As distribuições
+  6/7/9 instaladas têm os bundles exatos, mas não launcher compatível; `db up` falha fechado em vez de
+  substituir pelo launcher Java 21 da versão 11;
+- Data Grid 1 está coberto, mas os demais widgets Dojo continuam explicitamente
+  pendentes no manifesto legado;
+- o caminho React/Rollup otimizado do Mendix 10 está coberto por uma aplicação
+  criada do zero; o caminho React do Mendix 11 tem preflight limpo e builds Rspack completos de
+  LearnNow, MyFirstModule, SLATaskApp, Sudoku e VetClinic. Essa matriz comprova
+  os contratos auditados, não compatibilidade universal;
+- bundles web nativos são gerados; o pipeline React Native ainda depende dos
+  assets de template/projeto existentes;
+- `mx` e `mxbuild` não são fallbacks. Um recurso sem compilador produz erro ou
+  entrada no manifesto de suporte.

data/docs/pt-BR/conventions.md

@@ -0,0 +1,19 @@
+# Convenções
+
+**Português** · [English](../en-US/conventions.md) · [Deutsch](../de-DE/conventions.md)
+
+- Preserve nomes qualificados Mendix nas referências.
+- Use `snake_case` nos arquivos Ruby sem mudar a identidade do artefato.
+- Faça preview de rename, move, remove e migração antes do apply.
+- Declare papéis de páginas e flows em projetos protegidos.
+- Dê uma home padrão a cada perfil de navegação.
+- Mapeie homes por papel a user roles com acesso ao alvo.
+- Prefira tokens a estilos literais locais.
+- Writers tipados alteram apenas campos explicitamente declarados.
+- Themes, widgets, resources e fontes Java fazem parte do round-trip.
+- Rode RSpec, branch report e RuboCop antes de enviar mudanças.
+
+A validação exata do Mendix 5 em Windows permanece documentada como limitação
+legada, mas não é um gate atual de entrega.
+
+[Voltar ao índice](README.md)

data/docs/pt-BR/design-system.md

@@ -0,0 +1,65 @@
+# Navegação e design system
+
+**Português** · [English](../en-US/design-system.md) · [Deutsch](../de-DE/design-system.md)
+
+Perfis são dados nativos Mendix. O MXRB lê e escreve home por página ou
+microflow, login, título traduzido, ícone, home por papel e menus recursivos.
+
+```ruby
+navigation do
+  profile :Responsive, home_page: "Sales.Home", app_title: "Loja" do
+    title :en_US, "Shop"
+    home_for :Administrator, microflow: "Sales.OpenDashboard"
+    item "Pedidos", page: "Sales.Order_Overview", icon: "shopping_cart"
+  end
+end
+```
+
+Ícones de navegação aceitos: `home`, `pets`/`heart`, `calendar`/
+`calendar_today`, `user`, `search`, `settings`, `trash`, `file`, `time` e
+`shopping_cart`. Também é possível informar diretamente um código Glyphicons
+inteiro válido do Mendix; nomes desconhecidos falham durante a geração.
+
+`project.design_system` inventaria propriedades CSS, variáveis Sass, temas e
+catálogos `design-properties.json`. O lint encontra tokens ausentes, cores
+literais e contratos de contraste abaixo do nível WCAG declarado.
+
+Tokens declarados na DSL Ruby são materializados em
+`theme/web/_mxrb-design-system.scss`, importado uma única vez por
+`theme/web/main.scss`. Tokens de cor também viram propriedades `ColorPicker`
+do Studio em `themesource/mxrb/web/design-properties.json`. Temas resolvem
+herança e override antes da escrita; conteúdo existente do `main.scss` é
+preservado. Ciclos, nomes inválidos e valores CSS estruturalmente inseguros são
+rejeitados.
+
+Themes, widgets, resources e fontes Java fazem round-trip por
+`.mxrb/assets.json`, com SHA-256 e validação contra traversal.
+
+Migrações de literais são preview-first:
+
+```ruby
+plan = project.plan_design_token_migration(
+  "#3366ff" => "var(--brand-primary)"
+)
+plan.changes.each { puts "#{_1.path}: #{_1.occurrences}" }
+plan.apply!
+```
+
+O apply rejeita arquivos alterados desde o preview e substitui cada arquivo
+atomicamente.
+
+Os mesmos fluxos estão disponíveis no CLI:
+
+```sh
+bundle exec mxrb design scan App.mpr
+bundle exec mxrb design scan App.mpr --json
+bundle exec mxrb design migrate App.mpr '#3366ff' 'var(--brand-primary)'
+bundle exec mxrb design migrate App.mpr '#3366ff' 'var(--brand-primary)' --apply
+```
+
+`scan` mostra nome, valor, tipo, tema e localização de cada token, além dos
+totais de cores literais e referências não resolvidas. `migrate` apenas mostra
+o plano até receber `--apply`. Pares de contraste declarados na DSL continuam
+sendo verificados por `mxrb lint` contra o nível WCAG configurado.
+
+[Voltar ao índice](README.md)

data/docs/pt-BR/entity-dsl.md

@@ -0,0 +1,116 @@
+# DSL de entidades
+
+**Português** · [English](../en-US/entity-dsl.md) · [Deutsch](../de-DE/entity-dsl.md)
+
+Arquivos criados por `mxrb entity new Modulo.Entidade` são avaliados dentro do
+bloco do módulo. Por isso, a declaração usa somente o nome local:
+
+```ruby
+entity :Animal do
+  documentation "Animal atendido pela clínica"
+  string :Name, required: true, unique: true, length: 120,
+                default: "", documentation: "Nome de exibição"
+  integer :Age, default: 0
+  long :ExternalId
+  float :Weight
+  decimal :Balance
+  boolean :Active, default: true
+  datetime :BirthDate
+  autonumber :Sequence
+  hashstring :PasswordHash
+  binary :Document
+  enum :Species, enumeration: "VetClinic.AnimalSpecies"
+end
+```
+
+Os tipos disponíveis são `string`, `integer`, `long`, `float`, `decimal`,
+`boolean`, `datetime`, `autonumber`, `hashstring`, `binary` e `enum`. As opções
+comuns são `default:`, `documentation:`, `required:` e `unique:`. Strings
+também aceitam `length:`; `enum` exige `enumeration:`. A enumeração é declarada
+separadamente com `enumeration`; um atributo de enum usa `enum`, não
+`enumeration`.
+
+```ruby
+enumeration :AnimalSpecies do
+  value :Dog, caption: "Dog"
+  value :Cat, caption: "Cat"
+end
+```
+
+## Associações
+
+O primeiro argumento é a entidade de destino qualificada. `name:` define o
+nome estável da associação.
+
+```ruby
+entity :Animal do
+  # Reference padrão: vários Animal podem apontar para um Owner (N:1).
+  association "VetClinic.Owner", name: "Animal_Owner"
+
+  # Reference 1:1: ambos os lados são proprietários da associação.
+  association "VetClinic.Passport", name: "Animal_Passport", owner: :Both
+
+  # ReferenceSet: muitos para muitos (N:N).
+  association "VetClinic.Tag", name: "Animal_Tags", type: :ReferenceSet
+
+  # ReferenceSet com propriedade em ambos os lados.
+  association "VetClinic.Group", name: "Animal_Groups",
+              type: :ReferenceSet, owner: :Both
+end
+```
+
+`type:` aceita `:Reference` (padrão) ou `:ReferenceSet`; `owner:` aceita
+`:Default` (padrão) ou `:Both`.
+
+## Índices, membros do sistema e generalização
+
+```ruby
+entity :Animal do
+  string :Name, required: true
+  datetime :BirthDate
+
+  index :Name
+  index :BirthDate, :Name
+
+  system_members owner: true, created_date: true,
+                 changed_date: true, changed_by: true
+end
+
+entity :VetUser do
+  generalizes "System.User"
+  string :Registration
+end
+```
+
+Índices são declarados dentro da entidade passando os atributos na ordem
+desejada. `system_members` habilita os membros de sistema Mendix.
+`generalizes` recebe a entidade base qualificada.
+
+## Persistência, eventos e acesso
+
+```ruby
+entity :AnimalSearchResult do
+  non_persistent!
+  string :Name
+end
+
+entity :Animal do
+  before_commit microflow: "VetClinic.VAL_Animal"
+  after_commit microflow: "VetClinic.ACT_AfterAnimalCommit"
+  before_delete microflow: "VetClinic.VAL_DeleteAnimal"
+  after_delete microflow: "VetClinic.ACT_AfterAnimalDelete"
+
+  access_rule "VetClinic.User",
+              create: true,
+              delete: false,
+              read: :all,
+              write: %i[Name BirthDate],
+              xpath: "[Active = true()]"
+end
+```
+
+Em `access_rule`, `read:` e `write:` aceitam `:all`, `:none` ou uma lista de
+atributos. Declare um ou mais papéis qualificados como primeiros argumentos.
+
+Use `mxrb entity --help` para o comando e `mxrb generate project.rb` seguido de
+`mxrb validate App.mpr` para validar o resultado.