mxrb 0.1.3 → 0.1.4

data/docs/en-US/project-structure.md

@@ -2,8 +2,18 @@
 
 [Português](../pt-BR/project-structure.md) · **English** · [Deutsch](../de-DE/project-structure.md)
 
-The Ruby tree produced by `mxrb export` separates app-wide policy, module
-behavior, preserved native units and filesystem assets:
+`mxrb export` has two explicit modes. `--mode mendix` is the default and keeps
+the layered Mendix DSL tree. `--mode ruby` creates a conventional executable
+Ruby application with a React + Vite frontend.
+
+## Mendix mode
+
+```sh
+bundle exec mxrb export App.mpr app-source --mode mendix
+```
+
+This tree separates app-wide policy, module behavior, preserved native units
+and filesystem assets:
 
 ```text
 project.rb
@@ -46,4 +56,184 @@ The same tree supports all four normal workflows:
 - Mendix project to editable Ruby;
 - Mendix export to Ruby and back to a structurally equivalent Mendix project.
 
+## Ruby mode
+
+Ruby mode can also start without an existing Mendix project:
+
+```sh
+bundle exec mxrb init CustomerPortal --mode ruby
+cd CustomerPortal
+bundle install
+npm install --prefix frontend
+bundle exec mxrb run .
+```
+
+This creates the conventional application directly with `app/models`,
+`app/dtos`, `app/services`, `app/pages`, and React + Vite. A reversible Mendix
+baseline is isolated under `.mxrb`; it does not dictate the editable source
+layout. Materialize the current project as an MPR with:
+
+```sh
+bundle exec mxrb generate project.rb build/CustomerPortal.mpr
+```
+
+New Ruby models become entities, DTOs become non-persistent entities, and the
+bidirectional declarations are synchronized into the MPR. Ruby or React code
+without a native Mendix representation remains checksum-embedded and returns
+unchanged on the next export. Compilation fails explicitly when a structural
+change cannot be represented, preventing a silent partial conversion.
+
+To convert an existing MPR, use:
+
+```sh
+bundle exec mxrb export App.mpr app-ruby --mode ruby
+```
+
+```text
+app/
+  models/
+  dtos/
+  services/
+  pages/
+config/application.rb
+frontend/
+  package.json
+  vite.config.ts
+  tsconfig.json
+  src/{main.tsx,App.tsx,types.ts,nanoflows.ts,app.css}
+project.rb
+.mxrb/
+  ruby-app.json
+  runtime/App.mpr
+  mendix/
+```
+
+Persistent entities become records. Non-persistent entities become DTO classes
+and always use the `_dto.rb` suffix, avoiding ambiguous `_2.rb` names. Services
+are ordinary Ruby classes and initially delegate to the pure-Ruby native
+interpreter. Pages expose native metadata to the React + TypeScript frontend.
+The export derives `types.ts` from entities, enumerations, pages, widgets,
+contexts, effects, and API contracts; `npm run typecheck` is part of the Vite build.
+
+Install the Ruby and frontend dependencies once, then start both processes with
+one command:
+
+```sh
+bundle install
+npm install --prefix frontend
+bundle exec mxrb run .
+```
+
+`mxrb run` supervises the loopback Ruby JSON API, served by Puma 8, and the
+Vite development server.
+Vite proxies `/api` to Ruby. Use `--server-port` for the backend port and
+`--client-port` for the frontend port. `--no-frontend` starts only the API.
+The former `--api-port` and `--port` names remain compatibility aliases.
+The global `--no-progress` option is optional and only hides progress output.
+
+Two opt-in stacks add familiar Ruby conventions without changing the default
+Ruby mode:
+
+```sh
+bundle exec mxrb init ServiceDesk --mode ruby --flymetothemoon
+bundle exec mxrb export App.mpr app-rails --mode ruby --onrails
+```
+
+`--flymetothemoon` adds Sinatra, Puma, ActiveRecord, Rake and RSpec.
+`--onrails` adds Rails, Puma, ActiveRecord and RSpec. Both keep React + Vite as
+the integrated application frontend and run through the same `mxrb run .`
+command. ActiveRecord migrations own Ruby-only tables; the MXRB manifest stays
+authoritative for the Mendix domain model and its round-trips.
+
+## Browser domain-model diagram
+
+Open one or more Mendix module domain models in a DBeaver-inspired ER diagram:
+
+```sh
+bundle exec mxrb diagram-er App.mpr --module Sales
+bundle exec mxrb diagram-er App.mpr --module Sales --module Billing \
+  --output build/App-layout.mpr
+```
+
+The sidebar can select several modules together and displays associations
+between them. The browser also supports entity search, drag-and-drop
+positioning, zoom, fit, auto-arrange, grid, attribute visibility, relationship
+routing and draggable source/target anchors. Persistent entities are blue,
+DTO/non-persistent entities yellow, and OQL views green. **Save layout to MPR**
+writes positions and local-association anchors to native Mendix fields;
+cross-module anchors, which have no native BSON field, use isolated MXRB visual
+metadata in the same safe copy. The default copy is `App.domain-layout.mpr`; an
+existing output requires `--force`.
+
+**Export PNG** downloads a high-resolution image of the selected modules using
+the current colors, attributes and routes. PNG export does not modify the MPR;
+save the layout separately when those positions must survive a round-trip.
+
+Foreground mode remains available and occupies the terminal until `Ctrl+C`.
+Use the managed lifecycle to keep the ER editor in the background; stopping it
+preserves the layout copy and neither the source MPR nor its files are edited or
+removed:
+
+```sh
+bundle exec mxrb diagram-er up App.mpr --module Sales
+bundle exec mxrb diagram-er status App.mpr
+bundle exec mxrb diagram-er down App.mpr
+bundle exec mxrb diagram-er up App.mpr       # resume the same copy
+bundle exec mxrb diagram-er destroy App.mpr --yes
+```
+
+`destroy` stops the server and removes only the copy and external contents
+created by that lifecycle. Management uses a private authenticated loopback
+endpoint; state and token are stored in permission-restricted local files.
+
+The editor UI is implemented in React + TypeScript and talks only to the Ruby
+server APIs. Its Vite bundle is compiled into `lib/mxrb/web_ui`, included in the
+gem, and served locally. Node.js is therefore not required to use the installed
+editor, and no CDN is contacted. To develop the UI, run `npm install`,
+`npm run typecheck`, and `npm run build` from `frontend/modeler`.
+ER, UML, OQL, and the generic `--mode ruby` backend share the same embedded
+Puma adapter. `puma ~> 8.0` is a direct MXRB dependency and brings
+`nio4r ~> 2.0` transitively; WEBrick is not part of the HTTP stack.
+
+## UML diagrams
+
+UML is an additional implementation independent from the ER editor. It uses
+port 4569 and does not change domain-model layout. The viewer combines class,
+microflow activity and call-sequence diagrams rendered with Mermaid:
+
+The same server publishes `http://127.0.0.1:4569/modeler`, a React + TypeScript
+visual catalog for modules, pages, microflows and nanoflows, navigation,
+security, integrations, and settings. This first expanded surface is read-only;
+mutations remain locked until they have fail-closed validation and round-trip
+guarantees equivalent to the ER editor.
+
+```sh
+bundle exec mxrb uml App.mpr
+bundle exec mxrb uml App.mpr --export=class --module Sales
+bundle exec mxrb uml App.mpr --export=activity \
+  --microflow=Sales.CreateOrder --format=plantuml
+bundle exec mxrb uml App.mpr --export=sequence \
+  --root=Sales.CreateOrder --depth=3
+bundle exec mxrb uml App.mpr --export=sequence --module=Sales
+```
+
+Without `--export`, the unified viewer is served at
+`http://127.0.0.1:4569`. Text export defaults to Mermaid; select PlantUML with
+`--format=plantuml`. Sequence diagrams accept either a depth-limited root or
+all calls internal to one module. The viewer uses the same React + TypeScript
+workspace, with Mermaid bundled locally so rendering also works offline.
+
+## Version transitions and round-trips
+
+Both modes retain the stable Mendix IDs and complete native baseline required
+for upgrades, downgrades and repeated round-trips. In Ruby mode, model/DTO
+declarations are reverse-compiled into the MPR. Ruby service bodies and React
+sources are stored with SHA-256 checksums in the MXRB source table inside the
+MPR, so a later `--mode ruby` export restores the exact edited files.
+
+Native Mendix behavior remains authoritative for constructs with no semantic
+Ruby-to-Mendix compiler yet; the coverage manifest records that status instead
+of silently claiming a conversion. The preserved Ruby/React source survives a
+Mendix round-trip even when it has no direct Studio Pro representation.
+
 [Back to the documentation index](README.md)

data/docs/en-US/runtime-ruby.md

@@ -0,0 +1,100 @@
+# Java-free runtime
+
+Ruby mode runs the backend without starting the Mendix Java Runtime. When an
+exported application opens, MXRB automatically migrates an environment-specific
+SQLite database, opens the microflow interpreter, registers lifecycle hooks,
+enforces security, and starts scheduled events.
+
+Profiles live under `config/environments/` and commonly use `development.env`,
+`qa.env`, `staging.env`, and `production.env`. Precedence is process environment,
+profile file, `.env.<profile>`, then `.env`. Select one with `--environment qa`
+or `MXRB_ENV=qa`; `mxrb env . --environment qa` shows sources and key names but
+never values.
+
+```bash
+mxrb run . --environment qa
+mxrb test App.mpr smoke.rb --native --environment qa
+```
+
+Each profile defaults to `.mxrb/runtime/<environment>.sqlite3`. Schema migration
+derives entities, attributes, associations, and system members; additive changes
+are idempotent and incompatible changes use a transactional rebuild. Non-
+persistent entities remain in memory.
+
+The Ruby API provides login and bearer tokens, sessions, schema, navigation,
+pages, microflows, CRUD, and published REST. Page and microflow roles, entity
+access rules, member rights, and the safe XPath subset are enforced for every
+request. Credentials come from `MXRB_USERS_JSON` and `MXRB_AUTH_TOKENS` and
+should be supplied by ignored local files or the deployment secret manager.
+
+Scheduled events use MXRB's stdlib scheduler with minute, hour, and day
+intervals, overlap protection, and supervised shutdown. IANA time zones such
+as `America/New_York` use `tzinfo`, including daylight-saving transitions.
+Unknown zones fail during scheduling instead of silently falling back to UTC;
+`UTC`, `local`, and numeric offsets such as `-04:00` are also supported.
+
+Sessions and scheduler coordination default to the native shared SQLite file
+`.mxrb/runtime/<environment>-shared.sqlite3`, with no external service. Multiple
+instances must point `MXRB_SHARED_STORE_PATH` to the same file. Idempotent
+event-slot claims and heartbeat-renewed overlap leases are atomic; an unfinished
+claim can be recovered after its lease expires. The default lease is 300 seconds
+and can be changed with `MXRB_SCHEDULER_LEASE_TTL`. Set the shared-store path to
+`:memory:`, `memory`, or `local` for explicit process-local mode.
+
+Java Custom Actions never start a JVM. Every permitted action must have an
+explicit Ruby adapter registered by qualified name in `config/adapters.rb`:
+
+```ruby
+Mxrb::RubyApp::Registry.register_java_custom_action('Orders.CalculateTotal') do |arguments|
+  Calculator.call(
+    items: arguments.fetch('Items'),
+    discount: arguments.fetch('Discount')
+  )
+end
+```
+
+Keys are the parameter names from the Mendix model. Basic values are evaluated
+in the microflow context; entity, microflow, and mapping references are passed
+as qualified names. The return value is assigned only when `UseReturnVariable`
+is enabled (or for the legacy shape that only declares `ResultVariableName`).
+An unregistered action fails closed with its name and registration guidance;
+there is no class discovery, JAR execution, or JVM fallback. REST, app services,
+SOAP, mappings, and document generation continue to use type-level Ruby
+adapters. The browser still runs JavaScript/React, while its backend and APIs run
+without the Java Runtime.
+
+## Ruby → Mendix → Ruby certification
+
+The reproducible certification scenario lives in
+[`spec/fixtures/flymetothemoon/project.rb`](../../spec/fixtures/flymetothemoon/project.rb).
+It models customers, products, orders, and order lines in Ruby, including an
+enumeration, indexes, associations, microflows, a nanoflow, a scheduled event,
+and a data-grid page. The
+[`spec/flymetothemoon_roundtrip_spec.rb`](../../spec/flymetothemoon_roundtrip_spec.rb)
+test verifies these use cases:
+
+- generate and validate a Mendix 11.12.1 MPR from the Ruby DSL;
+- export through the real CLI with `--mode ruby --flymetothemoon`;
+- require Sinatra, Puma, ActiveRecord, and RSpec while producing no Java, JAR,
+  or bytecode files;
+- execute creation, aggregation, branching, CRUD, and page metadata through the
+  Ruby Runtime and SQLite;
+- compile an unchanged app and structurally compare the MPR with its source;
+- add an attribute and replace a microflow with idiomatic Ruby;
+- export once more and prove that both the Ruby code and Mendix model survive a
+  second structurally identical round trip.
+
+Run the isolated case with:
+
+```bash
+bundle exec rspec spec/flymetothemoon_roundtrip_spec.rb
+```
+
+For generated interfaces, the declarative
+[`spec/fixtures/frontend_browser/sudoku_full_flow.json`](../../spec/fixtures/frontend_browser/sudoku_full_flow.json)
+scenario runs through `script/frontend_browser_acceptance` in a real Chromium.
+It covers board positions 73 and 74, selection, value entry, and Easy, Medium,
+and Hard transitions. Each critical click waits for the microflow POST plus the
+association GET and must finish within 250 ms. Gallery queries are filtered by
+context in SQLite; objects loaded through an inverse association retain that
+link when only attributes are committed.

data/docs/en-US/runtime-schema-migrations.md

@@ -0,0 +1,41 @@
+# Ruby runtime schema migrations
+
+`Mxrb::Runtime::SchemaMigrator` identifies Mendix entities, attributes, and
+associations by storage GUID. Renaming an artifact while preserving its GUID
+keeps the physical table or column and its data.
+
+## Safe policy
+
+- Creating tables and adding optional attributes is automatic and idempotent.
+- Required attributes are emitted as `NOT NULL`.
+- Making an existing attribute required rebuilds the table transactionally.
+  Existing `NULL` values use the declared default; without a default, the
+  migration is rejected.
+- Adding a required attribute to a populated table requires a default.
+- Compatible changes preserve entity and association rows.
+- Removing an entity, attribute, or association raises
+  `Mxrb::Runtime::UnsafeSchemaMigrationError` by default and leaves the
+  database unchanged.
+- After reviewing the plan and taking a backup, destructive cleanup can be
+  enabled with `allow_destructive: true`. Only artifacts recorded in MXRB
+  metadata are removed; unrelated tables are never inferred or deleted.
+
+Exported Ruby applications keep destructive migration disabled. For a
+controlled run after backup, set
+`MXRB_ALLOW_DESTRUCTIVE_MIGRATIONS=true` in the selected environment profile.
+Every other value remains fail-closed.
+
+```ruby
+database = SQLite3::Database.new('runtime.sqlite3')
+migrator = Mxrb::Runtime::SchemaMigrator.new(
+  project,
+  database: database,
+  allow_destructive: true
+)
+result = migrator.migrate!
+puts migrator.migration_plan.changes
+```
+
+DDL, data copying, metadata updates, and authorized cleanup share one SQLite
+transaction. Any constraint violation or other failure rolls back the complete
+migration.

data/docs/en-US/validation-matrix.md

@@ -2,7 +2,7 @@
 
 [Português](../pt-BR/validation-matrix.md) · **English** · [Deutsch](../de-DE/validation-matrix.md)
 
-Last updated: 2026-08-05.
+Last updated: 2026-08-11.
 
 The matrix exercises this pipeline using only MXRB:
 
@@ -27,6 +27,23 @@ are never modified.
 | `mendixlabs/TreeViewAndGridView` (`TreeviewDemo`) | 5.21.4 | v1 | 176 | pass |
 | `mendixlabs/TreeViewAndGridView` (`GridViewPlayground`) | 6.10.8 | v1 | 122 | pass |
 
+On August 11, `script/validate_matrix` repeated the matrix with **6/6 passes**:
+1,506 units, 1,734 artifacts, and 3,388 references in 16.381 seconds.
+
+## Additional local inventory
+
+`script/certify_mprs --cycles 2 --repair-hashes` certified seven additional
+MPRs through 14 consecutive round trips: **7/7 passes**, 2,799 units, 3,238
+artifacts, and 4,819 references. The set covers LearnNow, SLATaskApp,
+SLATaskAppNative, MyFirstModule, CourseManager, RubyBridgeSandbox, and
+VetClinic.
+
+SLATaskApp had one stale content hash and RubyBridgeSandbox had two. The gate
+repaired only `Unit.ContentsHash` in temporary copies, recorded the changed
+UUIDs, and preserved the original BSON bytes. Source files were not modified.
+The second round trip also exposed and fixed native-widget types deserialized
+as strings.
+
 The comparator used for this matrix includes:
 
 - project metadata and format;
@@ -162,6 +179,24 @@ and is also expanded into editable `native_unit` hashes in
 `.mxrb/native_units.rb`. Concise typed DSLs overlay that complete Ruby
 representation where available.
 
+## Widget certification
+
+`script/certify_widgets --browser-report REPORT.json App.mpr` is the fail-closed
+gate for native web compiler and Marketplace widgets actually used by a
+project. It jointly requires page/layout compilation without fallbacks, resolution of every
+pluggable ID to an MPK `.mjs` entry with SHA-256, a version-owned native Rspack
+build, and passing Chromium evidence that declares every exercised widget type
+and ID without visible Runtime/widget errors.
+
+Importing an MPK or compiling its bundle alone does not certify behavior.
+Widgets that require a datasource, attribute, or specific parent placement only
+pass in a browser scenario configured with that valid context. Future or
+unexercised packages fail as missing evidence instead of inheriting a universal
+compatibility claim.
+The React/TypeScript frontend for `--mode ruby` has a separate track: its
+Chromium report certifies those widgets without claiming that equivalent
+pluggable components also passed in the Mendix Runtime.
+
 ## Ruby semantic index
 
 The Ruby semantic index was built successfully from every original MPR in the
@@ -202,9 +237,9 @@ instead of dumping the complete removed and added flow bodies.
 
 ## Ruby evaluations and coverage gate
 
-The current suite contains 1,039 examples and passes with 100.00% line coverage
-(17,224/17,224 executable library lines) and 100.00% branch coverage
-(6,811/6,811 branches).
+The current suite contains 1,329 examples and passes with 100.00% line coverage
+(23,771/23,771 executable library lines) and 100.00% branch coverage
+(9,704/9,704 branches).
 Run the enforced gate with:
 
 ```sh

data/docs/pt-BR/README.md

@@ -13,6 +13,7 @@
 - [Roadmap Ruby-first](ruby-first-roadmap.md)
 - [Matriz de validação](validation-matrix.md)
 - [Compilador nativo e Runtime](compiler.md)
+- [Runtime Ruby sem Java e ambientes](runtime-ruby.md)
 - [Relatório de qualidade do build e Runtime](native-runtime-quality-report.md)
 - [Criação e edição de projetos](writing.md)
 - [Scaffolds de projeto](scaffolds.md)

data/docs/pt-BR/oql-sql.md

@@ -42,6 +42,47 @@ Os nomes físicos devem ser conferidos no banco criado pelo Runtime Mendix
 exato. Joins por caminho de associação são declarados não suportados enquanto
 os metadados de armazenamento do Runtime não puderem provar o join correto.
 
+## Conversão segura de SQL para OQL
+
+O caminho inverso aceita um subconjunto de `SELECT` em PostgreSQL, SQL Server
+ou ANSI e produz OQL lógico. Informar o projeto permite recuperar exatamente a
+capitalização dos módulos, entidades e atributos:
+
+```ruby
+projection = Mxrb.open("Shop.mpr") do |project|
+  project.sql_to_oql(
+    'SELECT p."name" FROM "shop$product" p WHERE p."name" = :Name',
+    dialect: :postgresql
+  )
+end
+
+puts projection.oql if projection.supported?
+# SELECT p/Name FROM Shop.Product p WHERE p/Name = $Name
+```
+
+O comando unificado `query` converte nas duas direções; `--input -` lê de stdin
+e `--json` retorna o resultado tipado:
+
+```sh
+bundle exec mxrb query \
+  'SELECT p."name" FROM "shop$product" p WHERE p."name" = :Name' \
+  --from sql --to oql --project Shop.mpr --dialect postgresql
+bundle exec mxrb query 'SELECT p/Name FROM Shop.Product p' \
+  --from oql --to sql --dialect sql_server
+bundle exec mxrb query --input query.sql --from sql --dialect sql_server --json
+```
+
+O subconjunto inclui aliases, joins explícitos, fontes separadas por vírgula,
+`WHERE`, `GROUP BY`, `HAVING`, `UNION`, `ORDER BY`, `LIMIT`/`OFFSET`, funções
+OQL conhecidas e parâmetros nomeados (`:Name`, `@Name` ou `$Name`). Tabelas
+físicas `module$entity` viram `Module.Entity`; sem `--project`, a capitalização
+é inferida e o resultado recebe confiança `inferred`.
+
+Escritas, múltiplas instruções, CTEs, subconsultas em `FROM`/`JOIN`, parâmetros
+posicionais, funções desconhecidas e extensões sem equivalente OQL seguro, como `ILIKE`,
+`DISTINCT ON`, `TOP`, `::` e concatenação `||`, retornam `supported? == false`
+com uma explicação em `warnings`.
+
 ## Análise dialect-aware
 
 `Oql::Analyzer` encontra padrões de custo e portabilidade na fonte original,

data/docs/pt-BR/project-structure.md

@@ -2,8 +2,18 @@
 
 **Português** · [English](../en-US/project-structure.md) · [Deutsch](../de-DE/project-structure.md)
 
-A árvore produzida por `mxrb export` separa políticas globais, comportamento
-dos módulos, unidades nativas preservadas e assets:
+`mxrb export` possui dois modos explícitos. `--mode mendix` é o padrão e mantém
+a árvore Mendix em DSL por camadas. `--mode ruby` cria uma aplicação Ruby
+convencional e executável com frontend React + Vite.
+
+## Modo Mendix
+
+```sh
+bundle exec mxrb export App.mpr app-source --mode mendix
+```
+
+Essa árvore separa políticas globais, comportamento dos módulos, unidades
+nativas preservadas e assets:
 
 ```text
 project.rb
@@ -29,4 +39,189 @@ manifesto são gravadas.
 A estrutura suporta Ruby para um Mendix novo, Ruby sobre baseline exportado,
 Mendix para Ruby editável e Mendix → Ruby → Mendix estruturalmente equivalente.
 
+## Modo Ruby
+
+O modo Ruby também pode começar sem um projeto Mendix existente:
+
+```sh
+bundle exec mxrb init CustomerPortal --mode ruby
+cd CustomerPortal
+bundle install
+npm install --prefix frontend
+bundle exec mxrb run .
+```
+
+Esse comando cria diretamente a aplicação convencional com `app/models`,
+`app/dtos`, `app/services`, `app/pages` e React + Vite. Um baseline Mendix
+reversível fica isolado em `.mxrb`; ele não determina a organização do código
+que será editado. Para materializar o projeto atual em um MPR:
+
+```sh
+bundle exec mxrb generate project.rb build/CustomerPortal.mpr
+```
+
+Models Ruby novos viram entidades, DTOs viram entidades non-persistent e as
+declarações bidirecionais são sincronizadas no MPR. Código Ruby ou React sem
+representação Mendix nativa permanece incorporado com checksum e reaparece
+intacto no próximo export. A compilação falha explicitamente quando uma mudança
+estrutural não pode ser representada, evitando conversão parcial silenciosa.
+
+Para converter um MPR que já existe, use:
+
+```sh
+bundle exec mxrb export App.mpr app-ruby --mode ruby
+```
+
+```text
+app/
+  models/
+  dtos/
+  services/
+  pages/
+config/application.rb
+frontend/
+  package.json
+  vite.config.ts
+  tsconfig.json
+  src/{main.tsx,App.tsx,types.ts,nanoflows.ts,app.css}
+project.rb
+.mxrb/
+  ruby-app.json
+  runtime/App.mpr
+  mendix/
+```
+
+Entidades persistentes viram records. Entidades non-persistent viram classes
+DTO e sempre usam o sufixo `_dto.rb`, evitando nomes ambíguos como `_2.rb`.
+Services são classes Ruby comuns e inicialmente delegam ao interpretador nativo
+em Ruby puro. Pages expõem metadados nativos ao frontend React + TypeScript.
+O export gera `types.ts` a partir de entidades, enumerações, páginas, widgets,
+contextos, efeitos e contratos de API; `npm run typecheck` integra o build Vite.
+
+Instale as dependências Ruby e do frontend uma vez e depois suba os dois
+processos com um único comando:
+
+```sh
+bundle install
+npm install --prefix frontend
+bundle exec mxrb run .
+```
+
+`mxrb run` supervisiona a API JSON Ruby em loopback, servida pelo Puma 8, e o
+servidor Vite. O Vite
+encaminha `/api` para Ruby. Use `--server-port` para a porta do backend e
+`--client-port` para a porta do frontend. `--no-frontend` inicia somente a API.
+Os nomes antigos `--api-port` e `--port` continuam como aliases compatíveis.
+`--no-progress` é global e opcional; apenas oculta a saída de progresso.
+
+Duas stacks opcionais adicionam convenções Ruby conhecidas sem alterar o modo
+Ruby padrão:
+
+```sh
+bundle exec mxrb init ServiceDesk --mode ruby --flymetothemoon
+bundle exec mxrb export App.mpr app-rails --mode ruby --onrails
+```
+
+`--flymetothemoon` adiciona Sinatra, Puma, ActiveRecord, Rake e RSpec.
+`--onrails` adiciona Rails, Puma, ActiveRecord e RSpec. Ambas mantêm React +
+Vite como frontend integrado da aplicação e usam o mesmo comando
+`mxrb run .`. As migrations do ActiveRecord controlam apenas tabelas Ruby; o
+manifesto MXRB continua autoritativo para o domain model Mendix e seus
+round-trips.
+
+## Diagrama do domain model no browser
+
+Abra os domain models de um ou mais módulos Mendix em um diagrama ER inspirado
+no DBeaver:
+
+```sh
+bundle exec mxrb diagram-er App.mpr --module Sales
+bundle exec mxrb diagram-er App.mpr --module Sales --module Billing \
+  --output build/App-layout.mpr
+```
+
+A barra lateral permite selecionar vários módulos ao mesmo tempo e mostra as
+associações entre eles. A página também oferece busca de entidades,
+posicionamento por drag-and-drop, zoom, ajuste à tela, auto-organização, grade,
+visibilidade de atributos, rotas de relacionamento e pontos de origem/destino
+arrastáveis. Entidades persistentes são azuis, DTOs/non-persistent amarelos e
+OQL views verdes. **Salvar layout no MPR** grava as posições e os pontos das
+associações locais nos campos Mendix nativos; âncoras cross-module, que não têm
+campo BSON nativo, ficam em metadados visuais isolados do MXRB na mesma cópia
+segura. A cópia padrão é `App.domain-layout.mpr`; para substituir uma saída
+existente é necessário `--force`.
+
+**Exportar PNG** baixa uma imagem em alta resolução dos módulos selecionados,
+respeitando as cores, a exibição de atributos e as rotas. A exportação não modifica
+o MPR; salve o layout separadamente quando as posições precisarem sobreviver ao
+round-trip.
+
+O modo direto continua disponível e ocupa o terminal até `Ctrl+C`. Para manter o
+editor ER em segundo plano, use o lifecycle gerenciado, que preserva a cópia de
+layout ao parar e nunca edita nem remove o MPR de origem:
+
+```sh
+bundle exec mxrb diagram-er up App.mpr --module Sales
+bundle exec mxrb diagram-er status App.mpr
+bundle exec mxrb diagram-er down App.mpr
+bundle exec mxrb diagram-er up App.mpr       # retoma a mesma cópia
+bundle exec mxrb diagram-er destroy App.mpr --yes
+```
+
+`destroy` para o servidor e remove somente a cópia e os conteúdos externos que
+esse lifecycle criou. O controle usa um endpoint privado autenticado em loopback;
+estado e token ficam em arquivos locais com permissões restritas.
+
+A interface do editor é implementada em React + TypeScript e consome somente as
+APIs do servidor Ruby. O bundle Vite é compilado em `lib/mxrb/web_ui`, incluído
+na gem e servido localmente; portanto Node.js não é necessário para usar o
+editor instalado e nenhum CDN é acessado. Para desenvolver a interface, use
+`npm install`, `npm run typecheck` e `npm run build` em `frontend/modeler`.
+ER, UML, OQL e o backend genérico de `--mode ruby` compartilham o mesmo
+adaptador Puma embutido. `puma ~> 8.0` é dependência direta do MXRB e traz
+`nio4r ~> 2.0` transitivamente; WEBrick não faz parte da pilha HTTP.
+
+## Diagramas UML
+
+UML é uma implementação adicional e independente do editor ER. Ela usa a porta
+4569 e não altera o layout do domain model. O viewer reúne diagramas de classe,
+atividade de microflows e sequência de chamadas, renderizados com Mermaid:
+
+O mesmo servidor publica `http://127.0.0.1:4569/modeler`, um catálogo visual
+React + TypeScript para módulos, páginas, microflows e nanoflows, navegação,
+segurança, integrações e configurações. Essa primeira superfície ampliada é
+somente leitura; mutações continuam bloqueadas até terem validação e roundtrip
+fail-closed equivalentes ao editor ER.
+
+```sh
+bundle exec mxrb uml App.mpr
+bundle exec mxrb uml App.mpr --export=class --module Sales
+bundle exec mxrb uml App.mpr --export=activity \
+  --microflow=Sales.CreateOrder --format=plantuml
+bundle exec mxrb uml App.mpr --export=sequence \
+  --root=Sales.CreateOrder --depth=3
+bundle exec mxrb uml App.mpr --export=sequence --module=Sales
+```
+
+Sem `--export`, o comando abre o viewer unificado em
+`http://127.0.0.1:4569`. A exportação textual usa Mermaid por padrão; selecione
+PlantUML com `--format=plantuml`. Diagramas de sequência aceitam uma raiz com
+profundidade limitada ou todas as chamadas internas de um módulo. O viewer usa
+o mesmo workspace React + TypeScript; Mermaid é empacotado localmente para que a
+renderização também funcione offline.
+
+## Transições de versão e round-trips
+
+Os dois modos mantêm IDs estáveis do Mendix e o baseline nativo completo usado
+em upgrades, downgrades e round-trips repetidos. No modo Ruby, declarações de
+models/DTOs são compiladas de volta no MPR. Os corpos Ruby dos services e os
+fontes React são armazenados com SHA-256 em uma tabela MXRB dentro do MPR; uma
+nova exportação `--mode ruby` restaura exatamente os arquivos editados.
+
+O comportamento Mendix nativo continua autoritativo para construções que ainda
+não possuem compilador semântico Ruby → Mendix. O manifesto de cobertura deixa
+esse estado explícito em vez de alegar uma conversão silenciosa. O código
+Ruby/React preservado sobrevive ao round-trip mesmo sem representação direta no
+Studio Pro.
+
 [Voltar ao índice](README.md)